net-sftp 4.0.2 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e7dc5adb1f352eecedf9c4d5f6150b32e0e26ccdd76cb6cb242c66fbe636fd4
-  data.tar.gz: e9b3ade5165aa0c1dbb61e64acd303794b16a31aa385472c3c513d983322fb3a
+  metadata.gz: 4d3d330529ea03b189dc54e18be90d35bb2bfb79374917e9e22a2fcd3d7d79ca
+  data.tar.gz: feaf13c15e37ea24c5ed45f52a842b0a8d4413cc2a27f1ee6de5a03a0975d527
 SHA512:
-  metadata.gz: 8534ab3b4109bd1e5333c1e4814e5e01a855c2f84c40f60d58bfb2d6303bdc1fab20bf8102b31ef2a1b8c408e6565a7a0a26ff1dbf1b1c48445dd2f9aa49bee8
-  data.tar.gz: b36ad98cdca42bdf48a29957105f4a104c2965280f983f937bfd64e8958b86a2354dc612e52404bba88374944bdda86016f4e06449e8fb541e26f74a0e0eeacc
+  metadata.gz: 3da2ef173bd6e6ac212cf3ae73243a887ae0d136fc01f03a06b383f00a6ea19a55d2f461f5fadff10d6991dd295c6fb9c826edf6557f1d2a831fe32f2782dfdf
+  data.tar.gz: e12c6bdf4efc55e51fbf6dbe3ddb12494b8f3b090e9786bdf6deb002a6966505e9a6a63440fdb43fb23da9c20fce7b0c40d2b2e5425dd095a97dfe1648102dfb

data/.github/workflows/ci.yml

@@ -6,7 +6,8 @@ permissions:
   contents: read
 jobs:
   test:
-    runs-on: ubuntu-latest
+    # setup-ruby has no builds of Ruby 3.1 and older for ubuntu-latest (26.04).
+    runs-on: ubuntu-24.04
     strategy:
       fail-fast: false
       matrix:

data/CHANGES.txt

@@ -1,3 +1,14 @@
+=== 4.1.0
+
+* BREAKING: Require Ruby 2.6 or later. Bundler on older Rubies resolves to 4.0.2. [#207]
+* BREAKING: `upload` and `download` no longer close an IO object passed in as the local side; `download` flushes it instead. Callers that relied on the close must close it themselves. [#202]
+* Security: An `FXP_VERSION` packet after the session is open now raises `Net::SFTP::Exception` instead of switching protocol version mid-session and dropping pending requests. [#193]
+* Security: A server can no longer make the client allocate without bound, or hang, by sending an ACL, extended attribute or directory listing count larger than the packet holds; such packets now raise `Net::SFTP::Exception`. [#192]
+* Single-file downloads keep up to `:requests` reads in flight (default 64) instead of waiting for each 32 KB reply, so large downloads are no longer bound by round-trip time. [#204]
+* `upload!` and `download!` now give new files and directories the source's permissions (masked to 0777, subject to the umask) like OpenSSH's sftp client, so executables stay executable and private files are no longer created world-readable. The new `:preserve` option also copies access and modification times and sets permissions exactly. As with OpenSSH, attributes are best effort: if they can't be read the transfer uses default permissions, and if they can't be set a warning is logged and the transfer still succeeds. [#203]
+* Added `Net::SFTP::Session#extensions`, the extensions the server advertised in its `FXP_VERSION` packet (such as `posix-rename@openssh.com`). [#195]
+* The `:version` option now caps the negotiated SFTP protocol version; servers that always reply with their own version (OpenSSH replies 3) used to be negotiated at that version instead of the one requested. [#194]
+
 === 4.0.2
 
 * Security: Recursive downloads refuse to follow an existing local symlink at a server-named path instead of writing through it. The local path passed by the caller may still be a symlink. Suggested in #162 by srosenhamer [#186]

data/README.rdoc

@@ -35,6 +35,9 @@ In a nutshell:
     # download a file or directory from the remote host
     sftp.download!("/path/to/remote", "/path/to/local")
 
+    # also copy access and modification times (permissions are always copied)
+    sftp.download!("/path/to/remote", "/path/to/local", :preserve => true)
+
     # grab data off the remote host directly to a buffer
     data = sftp.download!("/path/to/remote")
 

data/Rakefile

@@ -68,12 +68,14 @@ def change_version(&block)
   require_relative version_file
   pre = Net::SFTP::Version::PRE
   tiny = Net::SFTP::Version::TINY
-  result = block[pre: pre, tiny: Net::SFTP::Version::TINY]
+  minor = Net::SFTP::Version::MINOR
+  result = block[pre: pre, tiny: tiny, minor: minor]
   raise ArgumentError, "Version change logic should always return a pre" unless result.key?(:pre)
 
   new_pre = result[:pre]
   new_tiny = result[:tiny] || tiny
-  found = { pre: false, tiny: false }
+  new_minor = result[:minor] || minor
+  found = { pre: false, tiny: false, minor: false }
   File.open("#{version_file}.new", "w") do |f|
     File.readlines(version_file).each do |line|
       match =
@@ -105,10 +107,23 @@ def change_version(&block)
         end
       end
 
+      if new_minor != minor
+        match = /^(\s+MINOR\s+=\s+)#{minor}(\s*)$/.match(line)
+        if match
+          prefix = match[1]
+          postfix = match[2]
+          new_line = "#{prefix}#{new_minor}#{postfix}"
+          puts "Changing:\n  - #{line}  + #{new_line}"
+          line = new_line
+          found[:minor] = true
+        end
+      end
+
       f.write(line)
     end
     raise ArgumentError, "Cound not find line: PRE = \"#{pre}\" in #{version_file}" unless found[:pre]
     raise ArgumentError, "Cound not find line: TINY = \"#{tiny}\" in #{version_file}" unless found[:tiny] || new_tiny == tiny
+    raise ArgumentError, "Cound not find line: MINOR = \"#{minor}\" in #{version_file}" unless found[:minor] || new_minor == minor
   end
 
   FileUtils.mv version_file, "#{version_file}.old"
@@ -119,7 +134,7 @@ end
 namespace :vbump do
   desc "Final release"
   task :final do
-    change_version do |pre:, tiny:|
+    change_version do |pre:, tiny:, **|
       _ = tiny
       if pre.nil?
         { tiny: tiny + 1, pre: nil }
@@ -131,9 +146,18 @@ namespace :vbump do
     end
   end
 
+  desc "Minor release"
+  task :minor do
+    change_version do |pre:, minor:, **|
+      raise ArgumentError, "PRE is #{pre.inspect}; release it with vbump:final first" unless pre.nil?
+
+      { minor: minor + 1, tiny: 0, pre: nil }
+    end
+  end
+
   desc "Increment prerelease"
   task :pre, [:type] do |_t, args|
-    change_version do |pre:, tiny:|
+    change_version do |pre:, tiny:, **|
       puts " PRE => #{pre.inspect}"
       match = /^([a-z]+)(\d+)/.match(pre)
       raise ArgumentError, "Unexpected pre: #{pre}" if match.nil? && args[:type].nil?

data/lib/net/sftp/operations/download.rb

@@ -49,12 +49,26 @@ module Net; module SFTP; module Operations
   # * <tt>:progress</tt> - either a block or an object to act as a progress
   #   callback. See the discussion of "progress monitoring" below.
   # * <tt>:requests</tt> - the number of pending SFTP requests to allow at
-  #   any given time. When downloading an entire directory tree recursively,
-  #   this will default to 16. Setting this higher might improve throughput.
-  #   Reducing it will reduce throughput.
+  #   any given time. When downloading a single file, this is the number of
+  #   reads kept in flight and defaults to 64. When downloading an entire
+  #   directory tree recursively, it is the number of files and directories
+  #   transferred at once and defaults to 16. Setting this higher might
+  #   improve throughput, particularly on high-latency links. Reducing it
+  #   will reduce throughput.
   # * <tt>:read_size</tt> - the maximum number of bytes to read at a time
   #   from the source. Increasing this value might improve throughput. It
   #   defaults to 32,000 bytes.
+  # * <tt>:preserve</tt> - if true, the local files and directories get the
+  #   access and modification times of the remote ones, and their permissions
+  #   are set exactly, even on files that already exist and regardless of the
+  #   umask.
+  #
+  # Like OpenSSH's sftp client, new local files and directories are created
+  # with the permissions of the remote ones, without setuid, setgid and sticky
+  # bits and subject to the umask. Nothing is set when +local+ is an IO object.
+  # If the remote attributes can't be read, the download goes ahead with
+  # default permissions; if they can't be applied locally, a warning is logged
+  # and the download still succeeds.
   #
   # == Progress Monitoring
   #
@@ -155,6 +169,7 @@ module Net; module SFTP; module Operations
       @progress = progress || options[:progress]
       @options = options
       @active = 0
+      @directories = []
       @properties = options[:properties] || {}
       requests
       read_size
@@ -210,7 +225,8 @@ module Net; module SFTP; module Operations
 
       # A simple struct for encapsulating information about a single remote
       # file or directory that needs to be downloaded.
-      Entry = Struct.new(:remote, :local, :directory, :size, :handle, :offset, :sink)
+      Entry = Struct.new(:remote, :local, :directory, :size, :handle, :offset, :sink,
+                         :next_read, :pending, :window, :chunks, :eof, :attributes)
 
       #--
       # "ruby -w" hates private attributes, so we have to do these longhand
@@ -231,10 +247,19 @@ module Net; module SFTP; module Operations
         @read_size ||= positive_option(:read_size, DEFAULT_READ_SIZE)
       end
 
-      # The number of simultaneou SFTP requests to use to effect the download.
-      # Defaults to 16 for recursive downloads.
+      # The number of simultaneous SFTP requests to use to effect the download.
+      # Defaults to 16 for recursive downloads and 64 for single files.
       def requests
-        @requests ||= positive_option(:requests, recursive? ? 16 : 2)
+        @requests ||= positive_option(:requests, recursive? ? 16 : 64)
+      end
+
+      # The most reads a single file may have outstanding at once.
+      def read_window_limit
+        recursive? ? 1 : requests
+      end
+
+      def preserve?
+        options[:preserve]
       end
 
       def positive_option(name, default)
@@ -254,7 +279,12 @@ module Net; module SFTP; module Operations
           if entry.directory
             update_progress(:mkdir, entry.local)
             refuse_symlink!(entry.local) if server_named?(entry) && ::File.symlink?(entry.local)
-            ::Dir.mkdir(entry.local) unless ::File.directory?(entry.local)
+            created = !::File.directory?(entry.local)
+            ::Dir.mkdir(entry.local, local_permissions(entry, 0777) | 0300) if created
+            if created || preserve?
+              @directories << entry
+              stat_directory(entry) unless entry.attributes
+            end
             request = sftp.opendir(entry.remote, &method(:on_opendir))
             request[:entry] = entry
           else
@@ -262,7 +292,64 @@ module Net; module SFTP; module Operations
           end
         end
 
-        update_progress(:finish) if !active?
+        if !active?
+          set_directory_attributes
+          update_progress(:finish)
+        end
+      end
+
+      # Only entries listed by readdir come with attributes.
+      def stat_directory(entry)
+        @active += 1
+        sftp.stat(entry.remote) do |response|
+          @active -= 1
+          entry.attributes = remote_attributes(response, "stat #{entry.remote}")
+          process_next_entry
+        end
+      end
+
+      # Without the remote attributes the download goes ahead with default
+      # permissions and no times, as it would for a server that never sent any.
+      def remote_attributes(response, operation)
+        return response[:attrs] if response.ok?
+
+        debug { "#{operation} failed, using default attributes: #{response}" }
+        nil
+      end
+
+      # Deepest directories first, after their contents; setting attributes on
+      # a directory doesn't change its parent's modification time.
+      def set_directory_attributes
+        @directories.reverse_each do |entry|
+          next unless entry.attributes
+
+          permissions = local_permissions(entry, 0777)
+          permissions &= ~::File.umask unless preserve?
+          set_local_attributes(entry, permissions)
+        end
+        @directories.clear
+      end
+
+      # setuid, setgid and sticky bits are never applied, matching OpenSSH.
+      def local_permissions(entry, default)
+        permissions = entry.attributes && entry.attributes.permissions
+        permissions ? permissions & 0777 : default
+      end
+
+      # Like OpenSSH's sftp client, failing to set attributes only warns; the
+      # data has already been transferred.
+      def set_local_attributes(entry, permissions)
+        attempt_local("chmod", entry) { ::File.chmod(permissions, entry.local) } if permissions
+
+        attributes = entry.attributes
+        return unless preserve? && attributes && attributes.atime && attributes.mtime
+        attempt_local("utime", entry) { ::File.utime(attributes.atime, attributes.mtime, entry.local) }
+      end
+
+      def attempt_local(operation, entry)
+        yield
+      rescue SystemCallError => e
+        lwarn { "#{operation} #{entry.local} failed: #{e.message}" }
       end
 
       # Called when a remote directory is "opened" for reading, e.g. to
@@ -290,7 +377,9 @@ module Net; module SFTP; module Operations
           response[:names].each do |item|
             next if item.name == "." || item.name == ".."
             validate_entry_name!(entry, item.name)
-            stack << Entry.new(::File.join(entry.remote, item.name), ::File.join(entry.local, item.name), item.directory?, item.attributes.size)
+            child = Entry.new(::File.join(entry.remote, item.name), ::File.join(entry.local, item.name), item.directory?, item.attributes.size)
+            child.attributes = item.attributes
+            stack << child
           end
 
           # take this opportunity to enqueue more requests
@@ -316,11 +405,13 @@ module Net; module SFTP; module Operations
         entry.local != local
       end
 
+      # Like OpenSSH, the file is always created writable by its owner.
       def open_local_file(entry)
-        return ::File.open(entry.local, "wb") unless server_named?(entry) && defined?(::File::NOFOLLOW)
+        permissions = local_permissions(entry, 0666) | 0200
+        return ::File.open(entry.local, "wb", permissions) unless server_named?(entry) && defined?(::File::NOFOLLOW)
 
         begin
-          ::File.open(entry.local, "wb", :flags => ::File::NOFOLLOW)
+          ::File.open(entry.local, "wb", permissions, :flags => ::File::NOFOLLOW)
         rescue SystemCallError
           raise unless ::File.symlink?(entry.local)
           refuse_symlink!(entry.local)
@@ -346,45 +437,116 @@ module Net; module SFTP; module Operations
         process_next_entry
       end
 
-      # Called when a file has been opened. This will call #download_next_chunk
+      # Called when a file has been opened. This will call #request_reads
       # to initiate the data transfer.
       def on_open(response)
         entry = response.request[:entry]
         raise StatusException.new(response, "open #{entry.remote}") unless response.ok?
 
         entry.handle = response[:handle]
+        if entry.attributes || entry.local.respond_to?(:write)
+          start_download(entry)
+        else
+          request = sftp.fstat(entry.handle, &method(:on_fstat))
+          request[:entry] = entry
+        end
+      end
+
+      # Called when the attributes of a file opened by #open_file arrive.
+      def on_fstat(response)
+        entry = response.request[:entry]
+        entry.attributes = remote_attributes(response, "fstat #{entry.remote}")
+        start_download(entry)
+      end
+
+      def start_download(entry)
         entry.sink = entry.local.respond_to?(:write) ? entry.local : open_local_file(entry)
         entry.offset = 0
+        entry.next_read = 0
+        entry.pending = 0
+        entry.window = 1
+        entry.chunks = {}
+
+        request_reads(entry)
+      end
 
-        download_next_chunk(entry)
+      # Keeps up to entry.window reads of #read_size bytes outstanding until
+      # the server reports EOF. The window starts at one and grows with each
+      # data reply, so small files don't cost a burst of reads past their end.
+      def request_reads(entry)
+        while !entry.eof && entry.pending < entry.window
+          read_range(entry, entry.next_read, read_size)
+          entry.next_read += read_size
+        end
       end
 
-      # Initiates a read of the next #read_size bytes from the file.
-      def download_next_chunk(entry)
-        request = sftp.read(entry.handle, entry.offset, read_size, &method(:on_read))
+      def read_range(entry, offset, length)
+        entry.pending += 1
+        request = sftp.read(entry.handle, offset, length, &method(:on_read))
         request[:entry] = entry
-        request[:offset] = entry.offset
+        request[:offset] = offset
+        request[:length] = length
       end
 
-      # Called when a read from a file finishes. If the read was successful
-      # and returned data, this will call #download_next_chunk to read the
-      # next bit from the file. Otherwise the file will be closed.
+      # Called when a read from a file finishes. Replies can arrive out of
+      # order, so data is buffered until everything before it has been
+      # written. Once the server has reported EOF and no reads are left
+      # outstanding, the file is closed.
       def on_read(response)
         entry = response.request[:entry]
+        entry.pending -= 1
 
         if response.eof?
-          update_progress(:close, entry)
-          entry.sink.close
-          request = sftp.close(entry.handle, &method(:on_close))
-          request[:entry] = entry
+          entry.eof = true
         elsif !response.ok?
           raise StatusException.new(response, "read #{entry.remote}")
         else
-          entry.offset += response[:data].bytesize
-          update_progress(:get, entry, response.request[:offset], response[:data])
-          entry.sink.write(response[:data])
-          download_next_chunk(entry)
+          offset = response.request[:offset]
+          length = response.request[:length]
+          data = response[:data]
+
+          if data.empty? || data.bytesize > length
+            raise Net::SFTP::Exception, "read #{entry.remote} returned #{data.bytesize} bytes for a #{length} byte request"
+          end
+
+          # Servers may return less than asked for without being at EOF, and
+          # the reads after this one have already been sent.
+          read_range(entry, offset + data.bytesize, length - data.bytesize) if data.bytesize < length
+
+          entry.chunks[offset] = data
+          write_buffered_chunks(entry)
+          entry.window += 1 if entry.window < read_window_limit
         end
+
+        request_reads(entry)
+        close_file(entry) if entry.pending.zero?
+      end
+
+      def write_buffered_chunks(entry)
+        while (data = entry.chunks.delete(entry.offset))
+          update_progress(:get, entry, entry.offset, data)
+          entry.sink.write(data)
+          entry.offset += data.bytesize
+        end
+      end
+
+      def close_file(entry)
+        if entry.chunks.any?
+          raise Net::SFTP::Exception, "read #{entry.remote} hit EOF at #{entry.offset} but the server returned data beyond it"
+        end
+
+        update_progress(:close, entry)
+        # The caller's IO stays open, but is flushed so its data is written when download! returns.
+        if entry.sink.equal?(local)
+          entry.sink.flush if entry.sink.respond_to?(:flush)
+        else
+          entry.sink.close
+        end
+        unless entry.local.respond_to?(:write)
+          set_local_attributes(entry, preserve? ? local_permissions(entry, nil) : nil)
+        end
+        request = sftp.close(entry.handle, &method(:on_close))
+        request[:entry] = entry
       end
 
       # Called when a file handle is closed.

data/lib/net/sftp/operations/upload.rb

@@ -56,6 +56,15 @@ module Net; module SFTP; module Operations
   #   connection on packets over 256 KiB).
   # * <tt>:name</tt> - the filename to report to the progress monitor when
   #   an IO object is given as +local+. This defaults to "<memory>".
+  # * <tt>:preserve</tt> - if true, the remote files and directories get the
+  #   access and modification times of the local ones, and their permissions
+  #   are set even on files that already exist remotely.
+  #
+  # Like OpenSSH's sftp client, new remote files and directories are created
+  # with the permissions of the local ones, without setuid, setgid and sticky
+  # bits and subject to the server's umask. Nothing is set when +local+ is an
+  # IO object. If the server refuses to set the attributes after the data has
+  # been written, a warning is logged and the upload still succeeds.
   #
   # == Progress Monitoring
   #
@@ -154,6 +163,7 @@ module Net; module SFTP; module Operations
       @options = options
       @properties = options[:properties] || {}
       @active = 0
+      @directories = []
 
       self.logger = sftp.logger
 
@@ -169,7 +179,7 @@ module Net; module SFTP; module Operations
 
         @active += 1
         if @options[:mkdir]
-          sftp.mkdir(remote) do |response|
+          sftp.mkdir(remote, directory_attributes(local, remote)) do |response|
             @active -= 1
             raise StatusException.new(response, "mkdir `#{remote}'") unless response.ok?
             requests.times do
@@ -248,9 +258,13 @@ module Net; module SFTP; module Operations
         value
       end
 
+      def preserve?
+        options[:preserve]
+      end
+
       # A simple struct for recording metadata about the file currently being
       # uploaded.
-      LiveFile = Struct.new(:local, :remote, :io, :size, :handle)
+      LiveFile = Struct.new(:local, :remote, :io, :size, :handle, :attributes)
 
       # The default # of bytes to read from disk at a time.
       DEFAULT_READ_SIZE   = 32_000
@@ -268,7 +282,11 @@ module Net; module SFTP; module Operations
           if @uploads.any?
             write_next_chunk(@uploads.first)
           elsif !active?
-            update_progress(:finish)
+            if @directories.any?
+              set_directory_attributes
+            else
+              update_progress(:finish)
+            end
           end
           return false
         elsif @stack.last.empty?
@@ -288,7 +306,7 @@ module Net; module SFTP; module Operations
 
             @active += 1
             update_progress(:mkdir, rpath)
-            request = sftp.mkdir(rpath, &method(:on_mkdir))
+            request = sftp.mkdir(rpath, directory_attributes(lpath, rpath), &method(:on_mkdir))
             request[:dir] = rpath
           else
             open_file(lpath, rpath)
@@ -317,10 +335,11 @@ module Net; module SFTP; module Operations
           size = file.size
         end
 
-        metafile = LiveFile.new(name, remote, file, size)
+        attributes = local.respond_to?(:read) ? {} : attributes_for(file.stat)
+        metafile = LiveFile.new(name, remote, file, size, nil, attributes)
         update_progress(:open, metafile)
 
-        request = sftp.open(remote, "w", &method(:on_open))
+        request = sftp.open(remote, "w", attributes, &method(:on_open))
         request[:file] = metafile
       end
 
@@ -373,6 +392,49 @@ module Net; module SFTP; module Operations
         process_next_entry
       end
 
+      # setuid, setgid and sticky bits are never sent, matching OpenSSH.
+      def attributes_for(stat)
+        attributes = { :permissions => stat.mode & 0777 }
+        attributes.update(:atime => stat.atime.to_i, :mtime => stat.mtime.to_i) if preserve?
+        attributes
+      end
+
+      # The directory is created writable and searchable by its owner so its
+      # contents can be uploaded; its real attributes are set once everything
+      # else is done (see #set_directory_attributes).
+      def directory_attributes(local, remote)
+        stat = ::File.stat(local)
+        @directories << [remote, attributes_for(stat)]
+        { :permissions => (stat.mode & 0777) | 0300 }
+      end
+
+      # Deepest directories first; setting attributes on a directory doesn't
+      # change its parent's modification time.
+      def set_directory_attributes
+        @directories.reverse_each do |path, attributes|
+          @active += 1
+          sftp.setstat(path, attributes) do |response|
+            @active -= 1
+            warn_unless_ok(response, "setstat #{path}")
+            process_next_entry
+          end
+        end
+        @directories.clear
+      end
+
+      # Called when the +fsetstat+ for :preserve finishes.
+      def on_fsetstat(response)
+        @active -= 1
+        file = response.request[:file]
+        warn_unless_ok(response, "fsetstat #{file.remote}")
+      end
+
+      # Like OpenSSH's sftp client, failing to set attributes only warns; the
+      # data has already been transferred.
+      def warn_unless_ok(response, operation)
+        lwarn { "#{operation} failed: #{response}" } unless response.ok?
+      end
+
       # Attempts to send the next chunk from the given file (where +file+ is
       # a LiveFile instance).
       def write_next_chunk(file)
@@ -384,9 +446,15 @@ module Net; module SFTP; module Operations
           data = file.io.read(read_size)
           if data.nil?
             update_progress(:close, file)
+            if preserve? && file.attributes.any?
+              @active += 1
+              request = sftp.fsetstat(file.handle, file.attributes, &method(:on_fsetstat))
+              request[:file] = file
+            end
             request = sftp.close(file.handle, &method(:on_close))
             request[:file] = file
-            file.io.close
+            # An IO passed in by the caller is theirs to close.
+            file.io.close unless file.io.equal?(local)
             file.io = nil
             @uploads.delete(file)
           else

data/lib/net/sftp/protocol/01/attributes.rb

@@ -1,4 +1,5 @@
 require 'net/ssh/buffer'
+require 'net/sftp/protocol/bounded_read'
 
 module Net; module SFTP; module Protocol; module V01
 
@@ -39,6 +40,8 @@ module Net; module SFTP; module Protocol; module V01
     T_BLOCK_DEVICE = 8
     T_FIFO         = 9
 
+    extend Net::SFTP::Protocol::BoundedRead
+
     class <<self
       # Returns the array of attribute meta-data that defines the structure of
       # the attributes packet as described by this version of the protocol.
@@ -106,7 +109,8 @@ module Net; module SFTP; module Protocol; module V01
         # Parse the hash of extended data from the buffer.
         def parse_extended(buffer)
           extended = Hash.new
-          buffer.read_long.times do
+          # Each pair is two strings, at least 8 bytes.
+          read_bounded_count!(buffer, 8, "extended attribute").times do
             extended[buffer.read_string] = buffer.read_string
           end
           extended

data/lib/net/sftp/protocol/01/base.rb

@@ -54,7 +54,8 @@ module Net; module SFTP; module Protocol; module V01
     def parse_name_packet(packet)
       names = []
 
-      packet.read_long.times do
+      # Each entry is two strings and the attribute flags, at least 12 bytes.
+      read_bounded_count!(packet, 12, "name").times do
         filename = packet.read_string
         longname = packet.read_string
         attrs    = attribute_factory.from_buffer(packet)

data/lib/net/sftp/protocol/04/attributes.rb

@@ -69,7 +69,8 @@ module Net; module SFTP; module Protocol; module V04
         def parse_acl(buffer)
           acl_buf = Net::SSH::Buffer.new(buffer.read_string)
           acl = []
-          acl_buf.read_long.times do
+          # Each entry is three longs and a string, at least 16 bytes.
+          read_bounded_count!(acl_buf, 16, "ACL").times do
             acl << ACL.new(acl_buf.read_long, acl_buf.read_long, acl_buf.read_long, acl_buf.read_string)
           end
           acl

data/lib/net/sftp/protocol/04/base.rb

@@ -28,7 +28,8 @@ module Net; module SFTP; module Protocol; module V04
     def parse_name_packet(packet)
       names = []
 
-      packet.read_long.times do
+      # Each entry is a string, the attribute flags and the type, at least 9 bytes.
+      read_bounded_count!(packet, 9, "name").times do
         filename = packet.read_string
         attrs    = attribute_factory.from_buffer(packet)
         names   << name_factory.new(filename, attrs)

data/lib/net/sftp/protocol/base.rb

@@ -1,5 +1,6 @@
 require 'net/ssh/loggable'
 require 'net/sftp/constants'
+require 'net/sftp/protocol/bounded_read'
 
 module Net; module SFTP; module Protocol
 
@@ -10,6 +11,7 @@ module Net; module SFTP; module Protocol
     include Net::SSH::Loggable
     include Net::SFTP::Constants
     include Net::SFTP::Constants::PacketTypes
+    include Net::SFTP::Protocol::BoundedRead
 
     # The SFTP session object that acts as client to this protocol instance
     attr_reader :session

data/lib/net/sftp/protocol/bounded_read.rb

@@ -0,0 +1,25 @@
+require 'net/sftp/errors'
+
+module Net; module SFTP; module Protocol
+
+  # Several SFTP structures are a 32-bit item count followed by that many
+  # items. Net::SSH::Buffer returns nil instead of raising when a read runs
+  # past the end of the data, so a loop over an unchecked count from the
+  # server keeps allocating long after the packet is exhausted.
+  module BoundedRead
+    # Reads an item count from +buffer+ and raises Net::SFTP::Exception if it
+    # is missing, or larger than the remaining bytes could hold given that
+    # each item takes at least +min_item_size+ bytes.
+    def read_bounded_count!(buffer, min_item_size, what)
+      count = buffer.read_long
+      raise Net::SFTP::Exception, "truncated packet: missing #{what} count" if count.nil?
+
+      if count > buffer.available / min_item_size
+        raise Net::SFTP::Exception, "server sent #{count} #{what} entries in only #{buffer.available} bytes"
+      end
+
+      count
+    end
+  end
+
+end; end; end

data/lib/net/sftp/session.rb

@@ -68,6 +68,10 @@ module Net; module SFTP
     # the server has not yet responded to will be represented here.
     attr_reader :pending_requests
 
+    # The extensions the server advertised in its FXP_VERSION packet, as a
+    # hash of name => data (e.g. "posix-rename@openssh.com" => "1").
+    attr_reader :extensions
+
     # Creates a new Net::SFTP instance atop the given Net::SSH connection.
     # This will return immediately, before the SFTP connection has been properly
     # initialized. Once the connection is ready, the given block will be called.
@@ -81,6 +85,7 @@ module Net; module SFTP
       @input      = Net::SSH::Buffer.new
       self.logger = session.logger
       @state      = :closed
+      @extensions = {}
       @pending_requests = {}
 
       connect(&block)
@@ -924,19 +929,27 @@ module Net; module SFTP
       # version negotiation, instantiating the appropriate Protocol instance
       # and invoking the callback given to #connect, if any.
       def do_version(packet)
+        # Negotiation happens once. A later FXP_VERSION would swap the protocol
+        # driver and drop every pending request.
+        unless state == :init
+          raise Net::SFTP::Exception, "unexpected FXP_VERSION packet while session is #{state}"
+        end
+
         debug { "negotiating sftp protocol version, mine is #{HIGHEST_PROTOCOL_VERSION_SUPPORTED}" }
 
         server_version = packet.read_long
         debug { "server reports sftp version #{server_version}" }
 
-        negotiated_version = [server_version, HIGHEST_PROTOCOL_VERSION_SUPPORTED].min
+        # Servers reply with their own version whatever we offered (OpenSSH
+        # always says 3), so cap at the version we offered as well.
+        negotiated_version = [server_version, @version, HIGHEST_PROTOCOL_VERSION_SUPPORTED].compact.min
         info { "negotiated version is #{negotiated_version}" }
 
-        extensions = {}
+        @extensions = {}
         until packet.eof?
           name = packet.read_string
           data = packet.read_string
-          extensions[name] = data
+          @extensions[name] = data
         end
 
         @protocol = Protocol.load(self, negotiated_version)

data/lib/net/sftp/version.rb

@@ -49,10 +49,10 @@ module Net
       MAJOR = 4
 
       # The minor component of this version of the Net::SFTP library
-      MINOR = 0
+      MINOR = 1
 
       # The tiny component of this version of the Net::SFTP library
-      TINY  = 2
+      TINY  = 0
 
       # The prerelease component of this version of the Net::SFTP library
       # nil allowed

data/net-sftp.gemspec

@@ -16,6 +16,7 @@ Gem::Specification.new do |spec|
   spec.homepage      = "https://github.com/net-ssh/net-sftp"
   spec.license       = "MIT"
   spec.required_rubygems_version = Gem::Requirement.new(">= 0") if spec.respond_to? :required_rubygems_version=
+  spec.required_ruby_version = ">= 2.6"
 
   spec.extra_rdoc_files = [
     "LICENSE.txt",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: net-sftp
 version: !ruby/object:Gem::Version
-  version: 4.0.2
+  version: 4.1.0
 platform: ruby
 authors:
 - Jamis Buck
@@ -32,7 +32,7 @@ cert_chain:
   mMdUtmMoVbjbik3hqkY/18G03c3PoFNpL38VLKuyyROYz1DaCqOaRju3sbOoirD+
   piQTZDCWxeKuX0Iuxq02uxkYHfoGB6In0y3OOQ==
   -----END CERTIFICATE-----
-date: 2026-10-25 00:00:00.000000000 Z
+date: 2026-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-ssh
@@ -125,6 +125,7 @@ files:
 - lib/net/sftp/protocol/06/attributes.rb
 - lib/net/sftp/protocol/06/base.rb
 - lib/net/sftp/protocol/base.rb
+- lib/net/sftp/protocol/bounded_read.rb
 - lib/net/sftp/request.rb
 - lib/net/sftp/response.rb
 - lib/net/sftp/session.rb
@@ -144,7 +145,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.6'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="