net-scp 4.1.0 → 4.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8fd30ff1a8f383d70371edecd81dd7aeb7f98eea7735cb156eb27b027fd3e8a6
-  data.tar.gz: f4e232b5edbd50eeb342a665c0f73cb7d74f58b396b8e09f0adf7ad152804b33
+  metadata.gz: b666f903f4a48fb442f7ddea7efbdf5a222a44b7e2c9f7ae0cba5b6b8a126e10
+  data.tar.gz: 39032bdfeb545761cd2229af060ca0a79855e051ecab1123e2c68100deb03e19
 SHA512:
-  metadata.gz: 47a7b29bfa8a6658f529eeaa5606af0ecdb4c7f1fd9bc17ab71744f2d5156724c8e7e4ddddfa08c728352b4a116f84631892e073503b5f43eadbb7987521fce7
-  data.tar.gz: ecebbde9ce32e37d38e243b72be7297b953ecce7b9229a68fc82c54dd6f633ae53b4e9b9ff7a9068ed829a3ed573e7b52a89dcba7c86dc5025a953ed0d7c2ae2
+  metadata.gz: 8608726350662b31607e5beaa21d0276fa93942b045ac29a5762236b99b5a57925f9fde59a9fb59ebdd6ada2d6ccb1f52aa17f90e7ee196d2c7a714d66afce2d
+  data.tar.gz: 3c4112b0662c5401f6bc4e50aec2797a583faa5d67947ee3e46c2dd7f1d48ed074f49df9893910d08ea09f0625b14071d1d66d8f7390bff66dee60e1e7d19095

data/.github/pull_request_template.md

@@ -0,0 +1 @@
+<!-- After opening the PR, add a changelog.d/<PR number>.<type>.txt fragment (none, change, security, breaking or breaking-security) instead of editing CHANGES.txt; see CONTRIBUTING.md#changelog. -->

data/.github/workflows/changelog.yml

@@ -0,0 +1,18 @@
+name: Changelog
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+
+permissions:
+  contents: read
+
+jobs:
+  changelog:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # HEAD is the PR merged into the base branch; HEAD^1 is the base it was merged into.
+          fetch-depth: 2
+      - uses: net-ssh/changelogd@v1

data/.github/workflows/ci.yml

@@ -10,7 +10,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby-version: ['2.3', '2.4', '2.5', '2.6', '2.7', '3.0', '3.1', '3.2', '3.3', 'ruby-head']
+        ruby-version: ['2.6', '2.7', '3.0', '3.1', '3.2', '3.3', '3.4', '4.0', 'ruby-head']
     continue-on-error: ${{ matrix.ruby-version == 'ruby-head' }}
     steps:
       - uses: actions/checkout@v3
@@ -21,3 +21,20 @@ jobs:
           bundler-cache: true # runs 'bundle install' and caches installed gems automatically
       - name: Run Tests
         run: bundle exec rake test
+        env:
+          RUBYOPT: "--enable=frozen_string_literal"
+  test-legacy:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ['2.3', '2.4', '2.5']
+    steps:
+      - uses: actions/checkout@v3
+      # Plain docker run rather than container: the ruby:2.3/2.4 images' glibc is too old for the actions' Node.
+      # Not rake test: the Rakefile loads changelogd, which these Rubies can't install.
+      # No frozen_string_literal: net-ssh 6 mutates string literals.
+      - name: Run Tests
+        run: >-
+          docker run --rm -v "$PWD:/w" -w /w -e BUNDLE_GEMFILE=gemfiles/legacy.gemfile ruby:${{ matrix.ruby-version }}
+          sh -c 'bundle install --jobs 4 && bundle exec ruby -Ilib -Itest -e "Dir.glob(\"./test/test_*.rb\").each { |f| require f }"'

data/.gitignore

@@ -11,3 +11,4 @@ doc
 Gemfile.lock
 
 lib/net/ssh/version.rb.old
+/gemfiles/*.lock

data/CHANGES.txt

@@ -1,3 +1,35 @@
+=== 4.1.3
+
+* Load again on Ruby 2.3-2.5 (4.1.2 needed 2.5), and declare `required_ruby_version >= 2.3` [#112, #110]
+* Add a `quote:` option to `upload`/`download` for the remote path: `:posix` (default), `:windows` for Win32-OpenSSH under cmd.exe or PowerShell (double-quoted, `\` sent as `/`, paths containing `"`, `$`, `` ` ``, `%`, `!`, curly quotes, CR, LF or NUL rejected), `:none` to send the path unchanged to servers without a shell, or a callable. By default a leading `~` or `~/` is now left for the remote shell to expand to the home directory; such paths previously referred to a literal `~` entry in the login directory and usually failed. Thanks @ArtsiomMusin for the Windows patch in #34 [#109, #34, #9]
+* Recursive uploads no longer abort on a broken symlink: it is skipped with a warning, the rest is uploaded, and a Net::SCP::Error listing the skipped paths is raised at the end, like OpenSSH scp. Based on #23 by @maage. [#108, #23]
+
+=== 4.1.2
+
+* Security: Downloads no longer apply setuid, setgid or sticky bits sent by the server, check that a server-chosen local name matches the requested remote basename (as OpenSSH does since CVE-2019-6111), and 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. O_NOFOLLOW suggested in net-sftp#162 by srosenhamer [#104]
+* Security: Recursive downloads, and downloads into a directory, reject file names from the server that are not a single path component (such as `../x` or `a/b`) instead of writing outside the target directory. Reported in net-sftp#162 by srosenhamer [#103]
+* Raise `Net::SCP::Error` when the server ends a transfer before the SCP protocol finishes, instead of reporting a truncated transfer as successful [#105, #96]
+* Opening an `scp://` URI through `uri/open-scp` now percent-decodes the user, password and path (once, keeping a literal `+`) and passes an IPv6 address to SSH without its brackets, so `scp://user@[::1]/a%20b` downloads `/a b` from `::1`. Thanks @OskarEichler [#94]
+* Opening an `scp://` URI through `uri/open-scp` now writes the download into the OpenURI buffer as it arrives, so large files spill to a temporary file instead of being held in memory twice. Thanks @OskarEichler [#93]
+* Parsing an `scp://` URI with a valueless query entry (`?flag`) or an empty one (`?a=1&&b=2`) no longer raises `NoMethodError`, and `URI::SCP#options` reflects the current query after `query=`. Thanks @OskarEichler [#92]
+* Opening an `scp://` URI through `uri/open-scp` now calls `:progress_proc` with the number of bytes received, as OpenURI documents, instead of with the SCP progress arguments (which raised `ArgumentError` for a lambda), and calls `:content_length_proc` once with the file size. Thanks @OskarEichler [#91]
+* Opening an `scp://` URI through `uri/open-scp` now uses the port and password given in the URI; they were passed outside the `:ssh` options and ignored. Options given in `:ssh` still take precedence. Thanks @OskarEichler [#90]
+* Close the local file net-scp opened for an upload or download when the transfer fails, so it is not left open (and locked on Windows) [#89, #20]
+* With `preserve: true`, recursive downloads now keep directories' modification times, which were overwritten when their contents were created. Thanks @OskarEichler [#88]
+* `upload`/`upload!` with a zero, negative or non-Integer `:chunk_size` now raises `ArgumentError` before opening a channel; previously `0` hung forever sending empty chunks, a negative value or a String failed only after the channel was open, and a Float was silently truncated. Thanks @OskarEichler [#87]
+* Uploading from an IO that isn't at its start now announces only the remaining bytes, instead of the full size, which made the transfer hang or fail. Thanks @OskarEichler [#86]
+* Accept a `Pathname` as the local path for uploads and downloads; previously uploads looped forever and downloads kept only the last chunk. Thanks @OskarEichler [#85, #29]
+
+=== 4.1.1
+
+* Allow net-ssh 8
+* Fix frozen string literal compatibility [npezza93, mfazekas]
+  - Use mutable string for scp command construction
+  - Use mutable string for error_string initialization
+* Add Ruby 3.4 and ruby-head to CI matrix
+* Add Ruby 4.0+ compatibility (logger, rdoc gems)
+* Drop EOL Ruby 2.3-2.5 from CI
+
 === 3.0.0
 
 * NetSHH 6.* support

data/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing to net-scp
+
+Run the tests with `bundle exec rake test`.
+
+## Changelog
+
+Don't edit `CHANGES.txt`. Instead, add a fragment file to `changelog.d/` in your PR; the release's version bump (`rake vbump:*`) moves all fragments into a new `=== <version>` section at the top of `CHANGES.txt` and deletes them.
+
+A fragment is named `<number>.<type>.txt`, where `<number>` is the PR number (so open the PR first, then add the fragment), and contains a single UTF-8 paragraph: the entry as it should read in `CHANGES.txt`, without the bullet or prefix. Lines are joined, so it can be wrapped. If it doesn't end with a reference list such as `[#95, #101]` or `[GHSA-xxxx-xxxx-xxxx]`, ` [#<number>]` is appended.
+
+| Type                | Written as                     | Use for                                                      |
+| ------------------- | ------------------------------ | ------------------------------------------------------------ |
+| `breaking-security` | `* BREAKING: Security: <text>` | an incompatible change made for security                     |
+| `breaking`          | `* BREAKING: <text>`           | an incompatible change                                       |
+| `security`          | `* Security: <text>`           | a security fix or hardening                                  |
+| `change`            | `* <text>`                     | any other user-visible fix or feature                        |
+| `none`              | nothing                        | PRs with no user-visible change (tests, CI, docs, refactors) |
+
+Examples:
+
+```sh
+rake "changelog:new[102,change,Fixed uploading files with spaces in their names]"
+# changelog.d/102.change.txt -> * Fixed uploading files with spaces in their names [#102]
+
+echo 'Refuse downloads that write outside the target directory [GHSA-xxxx-xxxx-xxxx]' > changelog.d/103.security.txt
+touch changelog.d/104.none.txt
+```
+
+For several entries from one PR add a suffix: `102.change.txt`, `102.change.2.txt` (`changelog:new` picks the next free one).
+
+`rake changelog:check` validates the fragments and `rake changelog:preview` prints the section the next release would add. CI fails a PR that edits `CHANGES.txt` or doesn't add or modify a `changelog.d/<PR number>.<type>.txt` fragment, unless it only touches `changelog.d/` or a maintainer adds the `skip-changelog` label; Dependabot PRs are skipped.
+
+The full rules, including how a release orders the entries, are in the [changelogd README](https://github.com/net-ssh/changelogd#readme).

data/Gemfile

@@ -3,9 +3,16 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in mygem.gemspec
 gemspec
 
+gem "net-ssh", ">= 7.3.1"
+gem "logger" # no longer a default gem in Ruby 4.0+
+
 # TODO: add to gemspec
 gem "bundler", ">= 1.11"
 gem "rake", ">= 12.0"
+gem "rdoc"
+
+# git: rather than github:, which Bundler 1.x (the publish workflow uses 1.17.3) expands to an unsupported git:// URL.
+gem "changelogd", git: "https://github.com/net-ssh/changelogd.git", tag: "v1", group: :development
 
 gem 'byebug', group: %i[development test] if !Gem.win_platform? && RUBY_ENGINE == "ruby"
 

data/README.md

@@ -69,6 +69,24 @@ require 'uri/open-scp'
 data = open("scp://user@host/path/to/file.txt").read
 ```
 
+The remote path is escaped for a POSIX shell, except that a leading `~` or
+`~/` is left for the remote shell to expand to the home directory (`~user/` is
+not expanded). Use the `quote:` option of `upload`/`download` for other
+servers:
+
+```ruby
+# Win32-OpenSSH (cmd.exe or PowerShell): the path is double-quoted and "\" becomes "/".
+# Paths containing ", $, `, %, !, curly quotes, CR, LF or NUL raise ArgumentError.
+scp.upload! "/local/path", "C:\\Program Files\\App\\file.txt", quote: :windows
+
+# Servers that don't run a shell (MikroTik and other appliances): the path is
+# sent unchanged. Never use this with untrusted paths.
+scp.download! "flash/backup.rsc", "/local/backup.rsc", quote: :none
+
+# Or quote it yourself
+scp.upload! "/local/path", remote, quote: ->(path) { "'#{path}'" }
+```
+
 For more information, see Net::SCP.
 
 ## REQUIREMENTS:

data/Rakefile

@@ -1,7 +1,10 @@
 require "rubygems"
 require "rake"
 require "rake/clean"
-require "rdoc/task"
+begin
+  require "rdoc/task"
+rescue LoadError
+end
 require "bundler/gem_tasks"
 
 desc "When releasing make sure NET_SSH_BUILDGEM_SIGNED is set"
@@ -19,6 +22,16 @@ name = "net-scp"
 require_relative "lib/net/scp/version"
 version = Net::SCP::Version::CURRENT
 
+begin
+  require "changelogd/rake"
+rescue LoadError
+  # A git gem isn't on the load path under plain `rake`, as the release workflow runs it; bundler/setup could clash with the running rake.
+  require "bundler"
+  $LOAD_PATH.unshift(*Bundler.definition.specs["changelogd"].flat_map(&:full_require_paths))
+  require "changelogd/rake"
+end
+Changelogd::RakeTasks.new(version_file: "lib/net/scp/version.rb")
+
 namespace :cert do
   desc "Update public cert from private - only run if public is expired"
   task :update_public_when_expired do
@@ -67,20 +80,23 @@ Rake::TestTask.new do |t|
 end
 
 extra_files = %w[LICENSE.txt THANKS.txt CHANGES.txt ]
-RDoc::Task.new do |rdoc|
-  rdoc.rdoc_dir = "rdoc"
-  rdoc.title = "#{name} #{version}"
-  rdoc.generator = 'hanna' # gem install hanna-nouveau
-  rdoc.main = 'README.md'
-  rdoc.rdoc_files.include("README*")
-  rdoc.rdoc_files.include("bin/*.rb")
-  rdoc.rdoc_files.include("lib/**/*.rb")
-  extra_files.each { |file|
-    rdoc.rdoc_files.include(file) if File.exist?(file)
-  }
+if defined?(RDoc::Task)
+  RDoc::Task.new do |rdoc|
+    rdoc.rdoc_dir = "rdoc"
+    rdoc.title = "#{name} #{version}"
+    rdoc.generator = 'hanna' # gem install hanna-nouveau
+    rdoc.main = 'README.md'
+    rdoc.rdoc_files.include("README*")
+    rdoc.rdoc_files.include("bin/*.rb")
+    rdoc.rdoc_files.include("lib/**/*.rb")
+    extra_files.each { |file|
+      rdoc.rdoc_files.include(file) if File.exist?(file)
+    }
+  end
 end
 
 def change_version(&block)
+  Rake::Task["changelog:check"].invoke
   version_file = 'lib/net/scp/version.rb'
   require_relative version_file
   pre = Net::SCP::Version::PRE
@@ -130,6 +146,7 @@ def change_version(&block)
 
   FileUtils.mv version_file, "#{version_file}.old"
   FileUtils.mv "#{version_file}.new", version_file
+  Rake::Task["changelog:release"].invoke
 end
 
 namespace :vbump do

data/changelog.d/README.md

@@ -0,0 +1 @@
+Changelog fragments: one `<PR number>.<type>.txt` file per user-visible change, assembled into `CHANGES.txt` when the version is bumped. See [CONTRIBUTING.md](../CONTRIBUTING.md#changelog).

data/gemfiles/legacy.gemfile

@@ -0,0 +1,7 @@
+# Ruby 2.3-2.5: the last net-ssh and mocha releases that still install there.
+source 'https://rubygems.org'
+
+gemspec path: ".."
+
+gem "net-ssh", "< 7"
+gem "mocha", "< 2"

data/lib/net/scp/download.rb

@@ -50,8 +50,11 @@ module Net; class SCP
       when :file
         read_file(channel, directive)
       when :end
+        directory = channel[:stack].pop
+        if channel[:options][:preserve] && directory && directory[:times]
+          File.utime(directory[:times][:atime], directory[:times][:mtime], channel[:local])
+        end
         channel[:local] = File.dirname(channel[:local])
-        channel[:stack].pop
         channel[:state] = :finish if channel[:stack].empty?
       end
 
@@ -73,7 +76,7 @@ module Net; class SCP
     # Finishes off the read, sets the times for the file (if any), and then
     # jumps to either #finish_state (for single-file downloads) or
     # #read_directive_state (for recursive downloads). A 0-byte is sent to the
-    # server to indicate that the file was recieved successfully.
+    # server to indicate that the file was received successfully.
     def finish_read_state(channel)
       channel[:io].close unless channel[:io] == channel[:local]
 
@@ -126,19 +129,17 @@ module Net; class SCP
         raise Net::SCP::Error, ":recursive not specified for directory download"
       end
 
-      channel[:local] = File.join(channel[:local], directive[:name])
+      channel[:local] = local_path_for(channel, directive[:name])
 
-      if File.exist?(channel[:local]) && !File.directory?(channel[:local])
+      if File.symlink?(channel[:local])
+        raise Net::SCP::Error, "#{channel[:local]} is a symlink, refusing to follow it"
+      elsif File.exist?(channel[:local]) && !File.directory?(channel[:local])
         raise Net::SCP::Error, "#{channel[:local]} already exists and is not a directory"
       elsif !File.exist?(channel[:local])
-        Dir.mkdir(channel[:local], directive[:mode] | 0700)
+        Dir.mkdir(channel[:local], (directive[:mode] & 0777) | 0700)
       end
 
-      if channel[:options][:preserve] && channel[:times]
-        File.utime(channel[:times][:atime], channel[:times][:mtime], channel[:local])
-      end
-
-      channel[:stack] << directive
+      channel[:stack] << directive.merge(:times => channel[:times])
       channel[:times] = nil
     end
 
@@ -146,20 +147,54 @@ module Net; class SCP
     # actual read.
     def read_file(channel, directive)
       if !channel[:local].respond_to?(:write)
-        directive[:name] = (channel[:options][:recursive] || File.directory?(channel[:local])) ?
-          File.join(channel[:local], directive[:name]) :
-          channel[:local]
+        server_named = channel[:options][:recursive] || File.directory?(channel[:local])
+        directive[:name] = server_named ? local_path_for(channel, directive[:name]) : channel[:local]
       end
 
       channel[:file] = directive.merge(:times => channel[:times])
+      # Setuid/setgid/sticky bits are never taken from the server, even with :preserve.
       channel[:io] = channel[:local].respond_to?(:write) ? channel[:local] :
-        File.new(directive[:name], "wb", directive[:mode] | 0600)
+        open_local_file(directive[:name], (directive[:mode] & 0777) | 0600, server_named)
       channel[:times] = nil
       channel[:remaining] = channel[:file][:size]
       channel[:state] = :read_data
 
       progress_callback(channel, channel[:file][:name], 0, channel[:file][:size])
     end
+
+    # The name comes from the server, so anything but a single path component
+    # would let a malicious server write outside the target (CVE-2019-6111).
+    def local_path_for(channel, name)
+      if name.empty? || name == "." || name == ".." || name.include?("/") || name.include?("\0") ||
+         (File::ALT_SEPARATOR && name.include?(File::ALT_SEPARATOR))
+        raise Net::SCP::Error, "invalid file name from server: #{name.inspect}"
+      end
+
+      if channel[:stack].empty? && !requested_name?(channel[:remote], name)
+        raise Net::SCP::Error, "file name from server does not match request: #{name.inspect}"
+      end
+
+      File.join(channel[:local], name)
+    end
+
+    # OpenSSH's CVE-2019-6111 check: the flags mirror its brace expansion plus fnmatch(3) with flags 0.
+    def requested_name?(remote, name)
+      pattern = File.basename(remote.to_s)
+      name == pattern || File.fnmatch(pattern, name, File::FNM_DOTMATCH | File::FNM_EXTGLOB)
+    end
+
+    # A symlink planted at a server-named path must not redirect the write;
+    # the caller's own target may be a symlink on purpose (net-sftp#162).
+    def open_local_file(path, perm, nofollow)
+      return File.new(path, "wb", perm) unless nofollow && defined?(File::NOFOLLOW)
+
+      begin
+        File.new(path, "wb", perm, :flags => File::NOFOLLOW)
+      rescue SystemCallError
+        raise unless File.symlink?(path)
+        raise Net::SCP::Error, "#{path} is a symlink, refusing to follow it"
+      end
+    end
   end
 
 end; end

data/lib/net/scp/upload.rb

@@ -49,7 +49,8 @@ module Net; class SCP
         directive = "D%04o %d %s\n" % [mode, 0, File.basename(channel[:current])]
         channel.send_data(directive)
         channel[:cwd] = channel[:current]
-        channel[:stack] << Dir.entries(channel[:current]).reject { |i| i == "." || i == ".." }
+        entries = Dir.entries(channel[:current]).reject { |i| i == "." || i == ".." }
+        channel[:stack] << entries.reject { |i| skip_broken_symlink(channel, File.join(channel[:current], i)) }
         await_response(channel, :next_item)
       end
     end
@@ -91,6 +92,7 @@ module Net; class SCP
     # upload and moves to #upload_current_state.
     def next_item_state(channel)
       if channel[:stack].empty?
+        channel[:state] = :finish
         finish_state(channel)
       else
         next_item = channel[:stack].last.shift
@@ -118,6 +120,32 @@ module Net; class SCP
       end
 
       channel[:size] = channel[:stat] ? channel[:stat].size : channel[:current].size
+      if channel[:current].respond_to?(:read) && channel[:current].respond_to?(:pos)
+        channel[:size] = [channel[:size] - channel[:current].pos, 0].max
+      end
+    end
+
+    # Returns true if +path+ is a symlink whose target doesn't exist, after
+    # logging a warning and recording it for #raise_if_entries_skipped.
+    def skip_broken_symlink(channel, path)
+      return false unless File.symlink?(path) && !File.exist?(path)
+
+      lwarn { "#{path}: broken symlink, skipping" }
+      (channel[:skipped] ||= []) << path
+      true
+    end
+
+    # Once the remote has closed the channel, raises a Net::SCP::Error listing
+    # the entries skipped by #skip_broken_symlink, if any.
+    def raise_if_entries_skipped(channel)
+      return unless channel.closing? && channel[:skipped]
+
+      # Cleared so it raises once, as on_process keeps calling this until the close is flushed.
+      skipped, channel[:skipped] = channel[:skipped], nil
+      # A failed remote scp is reported by start_command's exit-status check instead.
+      return unless channel[:exit].to_i.zero?
+
+      raise Net::SCP::Error, "upload incomplete, skipped broken symlinks: #{skipped.map(&:inspect).join(', ')}"
     end
 
     # If the :preserve option is set, send a 'T' directive and wait for the

data/lib/net/scp/version.rb

@@ -52,7 +52,7 @@ module Net
       MINOR = 1
 
       # The tiny component of this version of the Net::SSH library
-      TINY  = 0
+      TINY  = 3
 
       # The prerelease component of this version of the Net::SSH library
       # nil allowed

data/lib/net/scp.rb

@@ -1,3 +1,4 @@
+require 'pathname'
 require 'stringio'
 require 'shellwords'
 
@@ -64,7 +65,7 @@ module Net
   #     puts "#{name}: #{sent}/#{total}"
   #   end
   #
-  # Whenever a new chunk of data is recieved for or sent to a file, the callback
+  # Whenever a new chunk of data is received for or sent to a file, the callback
   # will be invoked, indicating the name of the file (local for downloads,
   # remote for uploads), the number of bytes that have been sent or received
   # so far for the file, and the size of the file.
@@ -258,13 +259,24 @@ module Net
     #
     # * :recursive - the +local+ parameter refers to a local directory, which
     #   should be uploaded to a new directory named +remote+ on the remote
-    #   server.
+    #   server. Broken symlinks in it are skipped with a warning, and once
+    #   everything else is uploaded a Net::SCP::Error listing them is raised.
     # * :preserve - the atime and mtime of the file should be preserved.
     # * :verbose - the process should result in verbose output on the server
     #   end (useful for debugging).
     # * :chunk_size - the size of each "chunk" that should be sent. Defaults
     #   to 2048. Changing this value may improve throughput at the expense
     #   of decreasing interactivity.
+    # * :quote - how +remote+ is quoted in the scp command run by the remote
+    #   shell. :posix (the default) escapes it for a POSIX shell, leaving a
+    #   leading "~" or "~/" unescaped so it expands to the remote home
+    #   directory ("~user/" is not expanded). :windows is for Win32-OpenSSH,
+    #   whose shell may be cmd.exe or PowerShell: backslashes become "/", the
+    #   path is wrapped in double quotes, and paths containing a double or curly
+    #   quote, $, `, %, !, CR, LF or NUL raise ArgumentError. :none sends the
+    #   path unchanged, for servers that don't run a shell (some routers and
+    #   appliances); never use it with untrusted input. A callable is given
+    #   +remote+ and returns the string to send.
     #
     # This method will return immediately, returning the Net::SSH::Connection::Channel
     # object that will support the upload. To wait for the upload to finish,
@@ -274,6 +286,10 @@ module Net
     #   channel = scp.upload("/local/path", "/remote/path")
     #   channel.wait
     def upload(local, remote, options={}, &progress)
+      chunk_size = options[:chunk_size] || Upload::DEFAULT_CHUNK_SIZE
+      unless chunk_size.is_a?(Integer) && chunk_size > 0
+        raise ArgumentError, ":chunk_size must be a positive Integer"
+      end
       start_command(:upload, local, remote, options, &progress)
     end
 
@@ -293,6 +309,7 @@ module Net
     # * :preserve - the atime and mtime of the file should be preserved.
     # * :verbose - the process should result in verbose output on the server
     #   end (useful for debugging).
+    # * :quote - how +remote+ is quoted for the remote shell (see #upload).
     #
     # This method will return immediately, returning the Net::SSH::Connection::Channel
     # object that will support the download. To wait for the download to finish,
@@ -329,7 +346,7 @@ module Net
       # (:verbose, :recursive, :preserve). Returns the command-line as a
       # string, ready to execute.
       def scp_command(mode, options)
-        command = "scp "
+        command = +"scp "
         command << (mode == :upload ? "-t" : "-f")
         command << " -v" if options[:verbose]
         command << " -r" if options[:recursive]
@@ -342,15 +359,15 @@ module Net
       # sets up a state machine to use to process the upload or download.
       # (See Net::SCP::Upload and Net::SCP::Download).
       def start_command(mode, local, remote, options={}, &callback)
-        session.open_channel do |channel|
-
-          if options[:shell]
-            escaped_file = shellescape(remote).gsub(/'/) { |m| "'\\''" }
-            command = "#{options[:shell]} -c '#{scp_command(mode, options)} #{escaped_file}'"
-          else
-            command = "#{scp_command(mode, options)} #{shellescape remote}"
-          end
+        local = local.to_path if local.is_a?(Pathname)
+        # Kept in channel[:remote] too, so a download's basename check sees "C:/a/b.txt" as b.txt.
+        remote = remote.to_s.tr("\\", "/") if options[:quote] == :windows
+        command = "#{scp_command(mode, options)} #{quote_remote(remote, options[:quote] || :posix)}"
+        if options[:shell]
+          command = "#{options[:shell]} -c '#{command.gsub("'") { "'\\''" }}'"
+        end
 
+        session.open_channel do |channel|
           channel.exec(command) do |ch, success|
             if success
               channel[:local   ] = local
@@ -360,22 +377,27 @@ module Net
               channel[:buffer  ] = Net::SSH::Buffer.new
               channel[:state   ] = "#{mode}_start"
               channel[:stack   ] = []
-              channel[:error_string] = ''
+              channel[:error_string] = +''
 
               channel.on_close do
-                # If we got an exit-status and it is not 0, something went wrong
-                if !channel[:exit].nil? && channel[:exit] != 0
-                  raise Net::SCP::Error, 'SCP did not finish successfully ' \
-                                         "(#{channel[:exit]}): #{channel[:error_string]}"
+                begin
+                  # The close can be dispatched before on_process has consumed data that arrived with it.
+                  send("#{channel[:state]}_state", channel)
+                  # If we got an exit-status and it is not 0, something went wrong
+                  if !channel[:exit].nil? && channel[:exit] != 0
+                    raise Net::SCP::Error, 'SCP did not finish successfully ' \
+                                           "(#{channel[:exit]}): #{channel[:error_string]}"
+                  end
+                  # A zero or missing exit-status does not prove the transfer completed.
+                  if channel[:state] != :finish
+                    message = +'SCP did not finish successfully (channel closed before end of transmission)'
+                    message << ": #{channel[:error_string]}" unless channel[:error_string].empty?
+                    raise Net::SCP::Error, message
+                  end
+                ensure
+                  io = channel[:io]
+                  io.close if io && io != channel[:local] && !io.closed?
                 end
-                # We may get no exit-status at all as returning a status is only RECOMENDED
-                # in RFC4254. But if our state is not :finish, something went wrong
-                if channel[:exit].nil? && channel[:state] != :finish
-                  raise Net::SCP::Error, 'SCP did not finish successfully ' \
-                                         '(channel closed before end of transmission)'
-                end
-                # At this point, :state can be :finish or :next_item
-                send("#{channel[:state]}_state", channel)
               end
               channel.on_data                   { |ch2, data| channel[:buffer].append(data) }
               channel.on_extended_data          { |ch2, type, data| debug { data.chomp } }
@@ -419,6 +441,7 @@ module Net
       # of the pipe, and allows the pipe to drain until the server closes it.
       def finish_state(channel)
         channel.eof!
+        raise_if_entries_skipped(channel)
       end
 
       # Invoked to report progress back to the client. If a callback was not
@@ -427,6 +450,29 @@ module Net
         channel[:callback].call(channel, name, sent, total) if channel[:callback]
       end
 
+      # Inside double quotes cmd.exe still expands % and !, PowerShell expands $ and `, and PowerShell also ends a string at U+2018..U+201E.
+      WINDOWS_UNSAFE = /["$`%!\r\n\0\u2018-\u201E]/
+
+      def quote_remote(remote, quote)
+        case quote
+        when :posix
+          remote = remote.to_s
+          return remote if remote == "~" || remote == "~/"
+          return "~/#{shellescape(remote[2..-1])}" if remote.start_with?("~/")
+          shellescape(remote)
+        when :windows
+          if remote.dup.force_encoding(Encoding::UTF_8) =~ WINDOWS_UNSAFE
+            raise ArgumentError, "remote path #{remote.inspect} contains a character that can't be quoted safely for a Windows shell"
+          end
+          "\"#{remote}\""
+        when :none
+          remote.to_s
+        else
+          raise ArgumentError, ":quote must be :posix, :windows, :none or a callable, got #{quote.inspect}" unless quote.respond_to?(:call)
+          quote.call(remote).to_s
+        end
+      end
+
       # Imported from ruby 1.9.2 shellwords.rb
       def shellescape(path)
         # Convert path to a string if it isn't already one.

data/lib/uri/open-scp.rb

@@ -8,9 +8,21 @@ module URI
 
   class SCP
     def buffer_open(buf, proxy, open_options)
-      options = open_options.merge(:port => port, :password => password)
+      options = open_options.dup
+      options[:ssh] = { :port => port }
+      options[:ssh][:password] = URI::DEFAULT_PARSER.unescape(password) if password
+      options[:ssh].merge!(open_options[:ssh] || {})
       progress = options.delete(:progress_proc)
-      buf << Net::SCP.download!(host, user, path, nil, options, &progress)
+      content_length = options.delete(:content_length_proc)
+      output = Object.new
+      output.define_singleton_method(:write) { |data| buf << data }
+      Net::SCP.download!(hostname, user && URI::DEFAULT_PARSER.unescape(user), URI::DEFAULT_PARSER.unescape(path), output, options) do |_channel, _name, received, total|
+        if content_length
+          content_length.call(total)
+          content_length = nil
+        end
+        progress.call(received) if progress
+      end
       buf.io.rewind
     end
 

data/lib/uri/scp.rb

@@ -11,8 +11,6 @@ module URI
       :query
     ].freeze
 
-    attr_reader :options
-
     def self.new2(user, password, host, port, path, query)
       new('scp', [user, password], host, port, nil, path, nil, query)
     end
@@ -20,14 +18,23 @@ module URI
     def initialize(*args)
       super(*args)
 
+      options
+    end
+
+    def options
+      return @options if defined?(@options_query) && @options_query == query
+
+      @options_query = query && query.dup
       @options = Hash.new
       (query || "").split(/&/).each do |pair|
+        next if pair.empty?
         name, value = pair.split(/=/, 2)
         opt_name = name.to_sym
-        values = value.split(/,/).map { |v| v.to_i.to_s == v ? v.to_i : v }
+        values = value.to_s.split(/,/).map { |v| v.to_i.to_s == v ? v.to_i : v }
         values = values.first if values.length == 1
-        options[opt_name] = values
+        @options[opt_name] = values
       end
+      @options
     end
   end
 

data/net-scp-public_cert.pem

@@ -1,7 +1,7 @@
 -----BEGIN CERTIFICATE-----
 MIIDeDCCAmCgAwIBAgIBATANBgkqhkiG9w0BAQsFADBBMQ8wDQYDVQQDDAZuZXRz
 c2gxGTAXBgoJkiaJk/IsZAEZFglzb2x1dGlvdXMxEzARBgoJkiaJk/IsZAEZFgNj
-b20wHhcNMjQxMjI1MTEzNDQ3WhcNMjUxMjI1MTEzNDQ3WjBBMQ8wDQYDVQQDDAZu
+b20wHhcNMjYwNTE2MTYyMDUzWhcNMjcwNTE2MTYyMDUzWjBBMQ8wDQYDVQQDDAZu
 ZXRzc2gxGTAXBgoJkiaJk/IsZAEZFglzb2x1dGlvdXMxEzARBgoJkiaJk/IsZAEZ
 FgNjb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDGJ4TbZ9H+qZ08
 pQfJhPJTHaDCyQvCsKTFrL5O9z3tllQ7B/zksMMM+qFBpNYu9HCcg4yBATacE/PB
@@ -12,10 +12,10 @@ KP4yMn+TzaXijyjRg7gECfJr3TGASaA4bQsILFGG5dAWcwO4OMrZedR7SHj/o0Kf
 3gL7P0axAgMBAAGjezB5MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgSwMB0GA1UdDgQW
 BBQF8qLA7Z4zg0SJGtUbv3eoQ8tjIzAfBgNVHREEGDAWgRRuZXRzc2hAc29sdXRp
 b3VzLmNvbTAfBgNVHRIEGDAWgRRuZXRzc2hAc29sdXRpb3VzLmNvbTANBgkqhkiG
-9w0BAQsFAAOCAQEAOEVGPubOS9dBQmiJYIZHOXe2Q50iQgxKa7hyEJcyA7q69Q5h
-Ha5r4WpZyW0Dkr0+jIkT8GS7hO0XnUZdOiuNFQrx30jfRSVT7680dF6wAHEQZJqC
-ZmYFthhR/mtzi7bA+Ubd0PyBNivqt3WhWP+Z19j1bVWIwzczUcFFao+FBjXptI0m
-VGRPnRIzATA2qQUuKGkwrNFSHD9tDIHXSvwJ62U9ahoMKfMoDP0WHdPIpFCB8bPg
-wxMvGTA/RH93o6dL09sq7rVtsS9NNFmBGJWLZWWPfcspNBUXS0HTWXsWS9XTm2bm
-bbXS+I4xE1yFIPs39ej57LGJDMgMhWTyJF2zVg==
+9w0BAQsFAAOCAQEAVx/yCCX0ZPQ8TFeZe1T+OBEn3Co/AfjAmCdhstf1TF+Jziyx
+dFJ8m8mF4596gru87Mi8mvu+WbPsLlFMOf5LDUkAsgnlvJ+zqNL7jPjGmsh0KOHJ
+0dzPYnTeGcfyrp1AXNN3Z2jWlEInrnqvo376vOmejjTtmDVVlhPjITHQqLSXzRaQ
+e3M8fbJ+nupobti6jpXCYvH86KtpaxF66mwaynfdjzxQAVycV/ilKtL+sHH8zxlg
+vNiMFH5yLu/tlav4xh+HlYscWVdFQIvd7f/Uxa+Vip1Pi16wmhnrE15z/vDX921v
+hukBRIoCEAuUgNVBh+L/C8aETzbf/77WU3Si/w==
 -----END CERTIFICATE-----

data/net-scp.gemspec

@@ -17,6 +17,7 @@ Gem::Specification.new do |spec|
   spec.homepage      = "https://github.com/net-ssh/net-scp"
   spec.license       = "MIT"
   spec.required_rubygems_version = Gem::Requirement.new(">= 0") if spec.respond_to? :required_rubygems_version=
+  spec.required_ruby_version = ">= 2.3"
   spec.metadata      = {
     "changelog_uri" => "https://github.com/net-ssh/net-scp/blob/master/CHANGES.txt"
   }
@@ -33,16 +34,16 @@ Gem::Specification.new do |spec|
     spec.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      spec.add_runtime_dependency(%q<net-ssh>, [">= 2.6.5", "< 8.0.0"])
+      spec.add_runtime_dependency(%q<net-ssh>, [">= 2.6.5", "< 9.0.0"])
       spec.add_development_dependency(%q<test-unit>, [">= 0"])
       spec.add_development_dependency(%q<mocha>, [">= 0"])
     else
-      spec.add_dependency(%q<net-ssh>, [">= 2.6.5", "< 8.0.0"])
+      spec.add_dependency(%q<net-ssh>, [">= 2.6.5", "< 9.0.0"])
       spec.add_dependency(%q<test-unit>, [">= 0"])
       spec.add_dependency(%q<mocha>, [">= 0"])
     end
   else
-    spec.add_dependency(%q<net-ssh>, [">= 2.6.5", "< 8.0.0"])
+    spec.add_dependency(%q<net-ssh>, [">= 2.6.5", "< 9.0.0"])
     spec.add_dependency(%q<test-unit>, [">= 0"])
     spec.add_dependency(%q<mocha>, [">= 0"])
   end

data/setup.rb

@@ -120,7 +120,7 @@ class ConfigTable
                ((major == 1) and
                 ((minor >= 5) or
                  ((minor == 4) and (teeny >= 4)))))
-  
+
   subprefix = lambda {|path|
     path.sub(/\A#{Regexp.quote(c['prefix'])}/o, '$prefix')
   }
@@ -172,7 +172,7 @@ class ConfigTable
                      'the directory for ruby scripts' ] ],
     [ 'so-dir',    [ sodir,
                      'path',
-                     'the directory for ruby extentions' ] ],
+                     'the directory for ruby extensions' ] ],
     [ 'data-dir',  [ '$prefix/share',
                      'path',
                      'the directory for shared data' ] ],
@@ -184,10 +184,10 @@ class ConfigTable
                      'the ruby program using for installation' ] ],
     [ 'make-prog', [ makeprog,
                      'name',
-                     'the make program to compile ruby extentions' ] ],
+                     'the make program to compile ruby extensions' ] ],
     [ 'without-ext', [ 'no',
                        'yes/no',
-                       'does not compile/install ruby extentions' ] ]
+                       'does not compile/install ruby extensions' ] ]
   ]
   multipackage_descripters = [
     [ 'with',      [ '',
@@ -303,7 +303,7 @@ class ConfigTable
         unless ConfigTable.config_key?(k)
     @table[k] = v
   end
-    
+
   def [](key)
     return nil unless @table[key]
     @table[key].gsub(%r<\$([^/]+)>) { self[$1] }
@@ -479,7 +479,7 @@ module FileOperations
   def ruby(str)
     command config('ruby-prog') + ' ' + str
   end
-  
+
   def make(task = '')
     command config('make-prog') + ' ' + task
   end
@@ -572,7 +572,7 @@ module HookScriptAPI
   def srcdirectory?(path)
     File.dir?(srcfile(path))
   end
-  
+
   def srcfile?(path)
     File.file? srcfile(path)
   end
@@ -606,10 +606,10 @@ class ToplevelInstaller
   TASKS = [
     [ 'config',   'saves your configurations' ],
     [ 'show',     'shows current configuration' ],
-    [ 'setup',    'compiles ruby extentions and others' ],
+    [ 'setup',    'compiles ruby extensions and others' ],
     [ 'install',  'installs files' ],
-    [ 'clean',    "does `make clean' for each extention" ],
-    [ 'distclean',"does `make distclean' for each extention" ]
+    [ 'clean',    "does `make clean' for each extension" ],
+    [ 'distclean',"does `make distclean' for each extension" ]
   ]
 
   def ToplevelInstaller.invoke
@@ -708,7 +708,7 @@ class ToplevelInstaller
       when '-v', '--version'
         puts "#{File.basename($0)} version #{Version}"
         exit 0
-      
+
       when '--copyright'
         puts Copyright
         exit 0
@@ -911,7 +911,7 @@ class ToplevelInstallerMulti < ToplevelInstaller
 
   def print_usage(f)
     super
-    f.puts 'Inluded packages:'
+    f.puts 'Included packages:'
     f.puts '  ' + @packages.sort.join(' ')
     f.puts
   end
@@ -1146,7 +1146,7 @@ class Installer
 
   def install_dir_ext(rel)
     return unless extdir?(curr_srcdir())
-    install_files ruby_extentions('.'),
+    install_files ruby_extensions('.'),
                   "#{config('so-dir')}/#{File.dirname(rel)}",
                   0555
   end
@@ -1165,9 +1165,9 @@ class Installer
   def ruby_scripts
     collect_filenames_auto().select {|n| /\.rb\z/ =~ n || "module.yml" == n }
   end
-  
+
   # picked up many entries from cvs-1.11.1/src/ignore.c
-  reject_patterns = %w( 
+  reject_patterns = %w(
     core RCSLOG tags TAGS .make.state
     .nse_depinfo #* .#* cvslog.* ,* .del-* *.olb
     *~ *.old *.bak *.BAK *.orig *.rej _$* *$
@@ -1212,14 +1212,14 @@ class Installer
     }
   end
 
-  def ruby_extentions(dir)
-    _ruby_extentions(dir) or
-        raise InstallError, "no ruby extention exists: 'ruby #{$0} setup' first"
+  def ruby_extensions(dir)
+    _ruby_extensions(dir) or
+        raise InstallError, "no ruby extension exists: 'ruby #{$0} setup' first"
   end
 
   DLEXT = /\.#{ ::Config::CONFIG['DLEXT'] }\z/
 
-  def _ruby_extentions(dir)
+  def _ruby_extensions(dir)
     Dir.open(dir) {|d|
       return d.select {|fname| DLEXT =~ fname }
     }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: net-scp
 version: !ruby/object:Gem::Version
-  version: 4.1.0
+  version: 4.1.3
 platform: ruby
 authors:
 - Jamis Buck
@@ -14,7 +14,7 @@ cert_chain:
   -----BEGIN CERTIFICATE-----
   MIIDeDCCAmCgAwIBAgIBATANBgkqhkiG9w0BAQsFADBBMQ8wDQYDVQQDDAZuZXRz
   c2gxGTAXBgoJkiaJk/IsZAEZFglzb2x1dGlvdXMxEzARBgoJkiaJk/IsZAEZFgNj
-  b20wHhcNMjQxMjI1MTEzNDQ3WhcNMjUxMjI1MTEzNDQ3WjBBMQ8wDQYDVQQDDAZu
+  b20wHhcNMjYwNTE2MTYyMDUzWhcNMjcwNTE2MTYyMDUzWjBBMQ8wDQYDVQQDDAZu
   ZXRzc2gxGTAXBgoJkiaJk/IsZAEZFglzb2x1dGlvdXMxEzARBgoJkiaJk/IsZAEZ
   FgNjb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDGJ4TbZ9H+qZ08
   pQfJhPJTHaDCyQvCsKTFrL5O9z3tllQ7B/zksMMM+qFBpNYu9HCcg4yBATacE/PB
@@ -25,14 +25,14 @@ cert_chain:
   3gL7P0axAgMBAAGjezB5MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgSwMB0GA1UdDgQW
   BBQF8qLA7Z4zg0SJGtUbv3eoQ8tjIzAfBgNVHREEGDAWgRRuZXRzc2hAc29sdXRp
   b3VzLmNvbTAfBgNVHRIEGDAWgRRuZXRzc2hAc29sdXRpb3VzLmNvbTANBgkqhkiG
-  9w0BAQsFAAOCAQEAOEVGPubOS9dBQmiJYIZHOXe2Q50iQgxKa7hyEJcyA7q69Q5h
-  Ha5r4WpZyW0Dkr0+jIkT8GS7hO0XnUZdOiuNFQrx30jfRSVT7680dF6wAHEQZJqC
-  ZmYFthhR/mtzi7bA+Ubd0PyBNivqt3WhWP+Z19j1bVWIwzczUcFFao+FBjXptI0m
-  VGRPnRIzATA2qQUuKGkwrNFSHD9tDIHXSvwJ62U9ahoMKfMoDP0WHdPIpFCB8bPg
-  wxMvGTA/RH93o6dL09sq7rVtsS9NNFmBGJWLZWWPfcspNBUXS0HTWXsWS9XTm2bm
-  bbXS+I4xE1yFIPs39ej57LGJDMgMhWTyJF2zVg==
+  9w0BAQsFAAOCAQEAVx/yCCX0ZPQ8TFeZe1T+OBEn3Co/AfjAmCdhstf1TF+Jziyx
+  dFJ8m8mF4596gru87Mi8mvu+WbPsLlFMOf5LDUkAsgnlvJ+zqNL7jPjGmsh0KOHJ
+  0dzPYnTeGcfyrp1AXNN3Z2jWlEInrnqvo376vOmejjTtmDVVlhPjITHQqLSXzRaQ
+  e3M8fbJ+nupobti6jpXCYvH86KtpaxF66mwaynfdjzxQAVycV/ilKtL+sHH8zxlg
+  vNiMFH5yLu/tlav4xh+HlYscWVdFQIvd7f/Uxa+Vip1Pi16wmhnrE15z/vDX921v
+  hukBRIoCEAuUgNVBh+L/C8aETzbf/77WU3Si/w==
   -----END CERTIFICATE-----
-date: 2025-01-22 00:00:00.000000000 Z
+date: 2026-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-ssh
@@ -43,7 +43,7 @@ dependencies:
         version: 2.6.5
     - - "<"
       - !ruby/object:Gem::Version
-        version: 8.0.0
+        version: 9.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -53,7 +53,7 @@ dependencies:
         version: 2.6.5
     - - "<"
       - !ruby/object:Gem::Version
-        version: 8.0.0
+        version: 9.0.0
 - !ruby/object:Gem::Dependency
   name: test-unit
   requirement: !ruby/object:Gem::Requirement
@@ -91,15 +91,20 @@ extra_rdoc_files:
 - LICENSE.txt
 - README.md
 files:
+- ".github/pull_request_template.md"
+- ".github/workflows/changelog.yml"
 - ".github/workflows/ci.yml"
 - ".gitignore"
 - CHANGES.txt
+- CONTRIBUTING.md
 - Gemfile
 - LICENSE.txt
 - Manifest
 - README.md
 - Rakefile
 - SECURITY.md
+- changelog.d/README.md
+- gemfiles/legacy.gemfile
 - lib/net/scp.rb
 - lib/net/scp/download.rb
 - lib/net/scp/errors.rb
@@ -123,7 +128,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="