net-ssh 7.3.6 → 8.0.0

data/lib/net/ssh.rb

@@ -8,6 +8,7 @@ require 'net/ssh/loggable'
 require 'net/ssh/transport/session'
 require 'net/ssh/authentication/session'
 require 'net/ssh/connection/session'
+require 'net/ssh/multiplex'
 require 'net/ssh/prompt'
 
 module Net
@@ -62,14 +63,15 @@ module Net
       auth_methods bind_address compression compression_level config
       encryption forward_agent hmac host_key identity_agent remote_user
       keepalive keepalive_interval keepalive_maxcount kex keys key_data
-      keycerts keycert_data languages logger paranoid password port proxy
+      keycerts keycert_data languages logger password port proxy
       rekey_blocks_limit rekey_limit rekey_packet_limit timeout verbose
       known_hosts global_known_hosts_file user_known_hosts_file host_key_alias
       host_name user properties passphrase keys_only max_pkt_size
       max_win_size send_env set_env use_agent number_of_password_prompts
       append_all_supported_algorithms non_interactive password_prompt
       agent_socket_factory minimum_dh_bits verify_host_key
-      fingerprint_hash check_host_ip pubkey_algorithms
+      fingerprint_hash check_host_ip pubkey_algorithms no_delay
+      control_master control_path
     ]
 
     # The standard means of starting a new SSH connection. When used with a
@@ -98,7 +100,10 @@ module Net
     #     ssh.loop
     #   end
     #
-    # This method accepts the following options (all are optional):
+    # This method accepts the following options (all are optional). Omit an
+    # option to use its default or ssh_config value; passing +nil+ (or an array
+    # containing +nil+) raises ArgumentError, except for :password,
+    # :passphrase, :logger and :password_prompt, where +nil+ means the default.
     #
     # * :auth_methods => an array of authentication methods to try
     # * :bind_address => the IP address on the connecting machine to use in
@@ -109,6 +114,40 @@ module Net
     # * :compression => the compression algorithm to use, or +true+ to use
     #   whatever is supported.
     # * :compression_level => the compression level to use when sending data
+    # * :control_master => set to +:auto+ to run the session through an
+    #   already running OpenSSH ControlMaster for the same host, port and user
+    #   (started e.g. with <tt>ssh -M</tt> or <tt>ControlMaster auto</tt>),
+    #   using its proxy mode (OpenSSH 7.4 or later). This skips the TCP
+    #   connection, key exchange and authentication. If there is no usable
+    #   master (no ControlPath, no socket, refused, timed out, owned by another
+    #   user) Net::SSH logs why and connects as usual; it never starts a master
+    #   itself. The master's own settings then apply instead of the options
+    #   for setting up a connection (:keys, :key_data, :password, :passphrase,
+    #   :auth_methods, :verify_host_key, :known_hosts, :host_key, :kex,
+    #   :encryption, :hmac, :compression, :rekey_*, :proxy, :keepalive and the
+    #   like); explicitly passed ones are named in a logger warning. Over the
+    #   master, remote port forwarding (Service::Forward#remote and
+    #   #cancel_remote) raises Net::SSH::NotSupportedOverControlMaster, as the
+    #   master consumes the global request reply, so success, failure and the
+    #   port allocated for port 0 can't be observed; other global requests
+    #   raise it too. Agent and X11 forwarding requests raise it
+    #   too, and :forward_agent can't be combined with it, because the master
+    #   serves them from its own agent or display only if it has ForwardAgent
+    #   or ForwardX11 enabled itself, and rejects them otherwise. Keepalive and
+    #   rekeying are left to the master. ssh_config's ControlMaster is
+    #   ignored, only this option enables it. An invalid ControlPath raises
+    #   ArgumentError. A missing or stale socket is logged at info level, a
+    #   socket that can't be used (another owner, refused, wrong protocol,
+    #   timed out) at warn level. Has no effect on Windows. Defaults to
+    #   +false+.
+    # * :control_path => the ControlMaster socket to use with
+    #   :control_master, with the same ~, ${ENV} and % tokens as ssh_config's
+    #   ControlPath (%C, %d, %h, %i, %j, %k, %L, %l, %n, %p, %r, %u, %%).
+    #   The master at that path decides which host and user the session is
+    #   connected to, so a fixed path without %h, %p, %r or %C sends every
+    #   host through the same master and the explicitly passed host key and
+    #   authentication options are ignored. Defaults to ControlPath from
+    #   ssh_config; +"none"+ disables the master.
     # * :config => set to +true+ to load the default OpenSSH config files
     #   (~/.ssh/config, /etc/ssh_config), or to +false+ to not load them, or to
     #   a file-name (or array of file-names) to load those specific configuration
@@ -137,7 +176,11 @@ module Net
     #   Defaults to +300+ seconds.
     # * :keepalive_maxcount => the maximun number of keepalive packet miss allowed.
     #   Defaults to 3
-    # * :kex => the key exchange algorithm (or algorithms) to use
+    # * :kex => the key exchange algorithm (or algorithms) to use. Like
+    #   KexAlgorithms, entries starting with +, - or ^ modify the default list.
+    #   diffie-hellman-group14-sha1 is supported but not offered unless listed
+    #   here (e.g. '+diffie-hellman-group14-sha1') or
+    #   :append_all_supported_algorithms is set.
     # * :keys => an array of file names of private keys to use for publickey
     #   and hostbased authentication
     # * :keycerts => an array of file names of key certificates to use
@@ -155,12 +198,24 @@ module Net
     #   packet. Default is 0x8000 (32768 bytes). Increase to 0x10000 (65536 bytes)
     #   for better performance if your SSH server supports it (most do).
     # * :max_win_size => maximum size we tell the other side that is supported for
-    #   the window.
+    #   the window, i.e. how much the server may send on a channel before net-ssh
+    #   reads it. Default is 0x200000 (2 MB), as in OpenSSH. Smaller values limit
+    #   how much data is in flight; some servers (e.g. Mikrotik) truncate output
+    #   when the window is small.
+    # * :minimum_dh_bits => the smallest group, in bits, accepted from the server
+    #   in diffie-hellman-group-exchange key exchange. Defaults to 2048, as in
+    #   OpenSSH; lower it (e.g. to 1024) only to reach legacy servers that offer
+    #   nothing larger.
+    # * :no_delay => turns Nagle's algorithm off on the connection's socket
+    #   (TCP_NODELAY), so a packet written while the previous one is still
+    #   unacknowledged is sent right away instead of waiting for the server's
+    #   ACK. OpenSSH does the same for every connection. Set to +false+ to keep
+    #   Nagle's algorithm on. Has no effect when the socket comes from a
+    #   ProxyCommand, whose command owns the TCP connection. Defaults to +true+.
     # * :non_interactive => set to true if your app is non interactive and prefers
     #   authentication failure vs password prompt. Non-interactive applications
     #   should set it to true to prefer failing a password/etc auth methods vs.
     #   asking for password.
-    # * :paranoid => deprecated alias for :verify_host_key
     # * :passphrase => the passphrase to use when loading a private key (default
     #   is +nil+, for no passphrase)
     # * :password => the password to use to login
@@ -168,11 +223,13 @@ module Net
     # * :properties => a hash of key/value pairs to add to the new connection's
     #   properties (see Net::SSH::Connection::Session#properties)
     # * :proxy => a proxy instance (see Proxy) to use when connecting
-    # * :pubkey_algorithms => the public key authentication algorithms to use for
-    #   this connection. Valid values are 'rsa-sha2-256-cert-v01@openssh.com',
-    #   'ssh-rsa-cert-v01@openssh.com', 'rsa-sha2-256', 'ssh-rsa'. Currently, this
-    #   option is only used for RSA public key authentication and ignored for other
-    #   types.
+    # * :pubkey_algorithms => the public key authentication algorithms to offer,
+    #   in order of preference (e.g. %w[ssh-ed25519 rsa-sha2-512 rsa-sha2-256]).
+    #   Keys whose type isn't listed are skipped. Like PubkeyAcceptedAlgorithms,
+    #   entries starting with +, - or ^ modify the default list. ssh-rsa (SHA-1),
+    #   ssh-rsa-cert-v01@openssh.com and ssh-dss are supported but not offered
+    #   unless listed here (e.g. '+ssh-rsa') or :append_all_supported_algorithms
+    #   is set.
     # * :rekey_blocks_limit => the max number of blocks to process before rekeying
     # * :rekey_limit => the max number of bytes to process before rekeying
     # * :rekey_packet_limit => the max number of packets to process before rekeying
@@ -184,7 +241,8 @@ module Net
     # * :user => the user name to log in as; this overrides the +user+
     #   parameter, and is primarily only useful when provided via an SSH
     #   configuration file.
-    # * :remote_user => used for substitution into the '%r' part of a ProxyCommand
+    # * :remote_user => used for substitution into the '%r' part of a ProxyCommand;
+    #   defaults to the user name the connection logs in as.
     # * :user_known_hosts_file => the location of the user known hosts file.
     #   Set to an array to specify multiple user known hosts files.
     #   Defaults to %w(~/.ssh/known_hosts ~/.ssh/known_hosts2).
@@ -196,7 +254,9 @@ module Net
     #   default. The symbols :debug, :info, :warn, :error, and :fatal are also
     #   supported and are translated to the corresponding Logger constant.
     # * :append_all_supported_algorithms => set to +true+ to append all supported
-    #   algorithms by net-ssh. Was the default behaviour until 2.10
+    #   algorithms by net-ssh, except the +none+ cipher and MAC, which must be
+    #   named explicitly (e.g. encryption: '+none'). Was the default behaviour
+    #   until 2.10
     # * :number_of_password_prompts => Number of prompts for the password
     #   authentication method defaults to 3 set to 0 to disable prompt for
     #   password auth method
@@ -211,21 +271,32 @@ module Net
     #   * :accept_new_or_local_tunnel (insecure) ::Net::SSH::Verifiers::AcceptNewOrLocalTunnel
     #   * :accept_new (insecure) ::Net::SSH::Verifiers::AcceptNew
     #   * :always (secure) ::Net::SSH::Verifiers::Always
-    #   You can also provide an own Object which responds to +verify+. The argument
-    #   given to +verify+ is a hash consisting of the +:key+, the +:key_blob+,
-    #   the +:fingerprint+ and the +:session+. Returning true accepts the host key,
-    #   returning false declines it and closes the connection.
+    #   You can also provide an own Object which responds to +verify+ and
+    #   +verify_signature+. The argument given to +verify+ is a hash consisting
+    #   of the +:key+, the +:key_blob+, the +:fingerprint+ and the +:session+.
+    #   Returning true accepts the host key, returning false declines it and
+    #   closes the connection. +verify_signature+ is given a block that checks
+    #   the server's host key signature and must return the block's result.
     # * :fingerprint_hash => 'MD5' or 'SHA256', defaults to 'SHA256'
     # If +user+ parameter is nil it defaults to USER from ssh_config, or
     # local username
     def self.start(host, user = nil, options = {}, &block)
+      if options.key?(:paranoid)
+        raise ArgumentError, ":paranoid has been removed, use :verify_host_key (same values)"
+      end
+
       invalid_options = options.keys - VALID_OPTIONS
       if invalid_options.any?
         raise ArgumentError, "invalid option(s): #{invalid_options.join(', ')}"
       end
 
+      reject_nil_options(options)
+      Multiplex.validate_options!(options)
+      explicit_options = options.keys
+      host_arg = host
+
+      options = options.dup
       assign_defaults(options)
-      _sanitize_options(options)
 
       options[:user] = user if user
       options = configuration_for(host, options.fetch(:config, true)).merge(options)
@@ -237,8 +308,6 @@ module Net
         options[:number_of_password_prompts] = 0
       end
 
-      _support_deprecated_option_paranoid(options)
-
       if options[:verbose]
         options[:logger].level = case options[:verbose]
                                  when Integer then options[:verbose]
@@ -251,26 +320,35 @@ module Net
                                  end
       end
 
-      transport = Transport::Session.new(host, options)
-      auth = Authentication::Session.new(transport, options)
-
       user = options.fetch(:user, user) || Etc.getpwuid.name
-      if auth.authenticate("ssh-connection", user, options[:password])
-        connection = Connection::Session.new(transport, options)
-        if block_given?
-          begin
-            yield connection
-          ensure
-            connection.close unless connection.closed?
-          end
-        else
-          return connection
+      options[:remote_user] ||= user
+
+      connection = Multiplex.connect(host_arg, host, user, options, explicit: explicit_options) if options[:control_master]
+      connection ||= connect_directly(host, user, options)
+
+      if block_given?
+        begin
+          yield connection
+        ensure
+          connection.close unless connection.closed?
         end
       else
+        connection
+      end
+    end
+
+    def self.connect_directly(host, user, options)
+      transport = Transport::Session.new(host, options)
+      auth = Authentication::Session.new(transport, options)
+
+      unless auth.authenticate("ssh-connection", user, options[:password])
         transport.close
         raise AuthenticationFailed, "Authentication failed for user #{user}@#{host}"
       end
+
+      Connection::Session.new(transport, options)
     end
+    private_class_method :connect_directly
 
     # Returns a hash of the configuration options for the given host, as read
     # from the SSH configuration file(s). If +use_ssh_config+ is true (the
@@ -304,31 +382,35 @@ module Net
       end
     end
 
-    def self._sanitize_options(options)
-      invalid_option_values = [nil, [nil]]
-      unless (options.values & invalid_option_values).empty?
-        nil_options = options.select { |_k, v| invalid_option_values.include?(v) }.map(&:first)
-        Kernel.warn "#{caller_locations(2, 1)[0]}: Passing nil, or [nil] to Net::SSH.start is deprecated for keys: #{nil_options.join(', ')}"
-      end
-    end
-    private_class_method :_sanitize_options
+    NIL_ALLOWED_OPTIONS = %i[password passphrase logger password_prompt].freeze
 
-    def self._support_deprecated_option_paranoid(options)
-      if options.key?(:paranoid)
-        Kernel.warn(
-          ":paranoid is deprecated, please use :verify_host_key. Supported " \
-          "values are exactly the same, only the name of the option has changed."
-        )
-        if options.key?(:verify_host_key)
-          Kernel.warn(
-            "Both :paranoid and :verify_host_key were specified. " \
-            ":verify_host_key takes precedence, :paranoid will be ignored."
-          )
-        else
-          options[:verify_host_key] = options.delete(:paranoid)
-        end
-      end
+    NIL_OPTION_HINTS = {
+      config: "config: false to skip ssh_config files",
+      proxy: "proxy: false to connect without a proxy",
+      keys: "keys: [] to use no key files",
+      use_agent: "use_agent: false to not use ssh-agent",
+      forward_agent: "forward_agent: false to not forward ssh-agent",
+      keepalive: "keepalive: false to send no keepalives",
+      compression: "compression: false to disable compression",
+      control_master: "control_master: false to not use a ControlMaster",
+      control_path: "control_path: 'none' to not use a ControlMaster socket",
+      send_env: "send_env: [] to send no environment variables",
+      set_env: "set_env: {} to set no environment variables"
+    }.freeze
+    private_constant :NIL_ALLOWED_OPTIONS, :NIL_OPTION_HINTS
+
+    def self.reject_nil_options(options)
+      nil_keys = options.select do |key, value|
+        !NIL_ALLOWED_OPTIONS.include?(key) && (value.nil? || (value.is_a?(Array) && value.include?(nil)))
+      end.keys
+      return if nil_keys.empty?
+
+      message = "nil is not allowed for #{nil_keys.map(&:inspect).join(', ')}; " \
+                "omit #{nil_keys.one? ? 'it' : 'them'} to use the default or ssh_config value"
+      hints = NIL_OPTION_HINTS.values_at(*nil_keys).compact
+      message += ", or pass #{hints.join(', or ')}" if hints.any?
+      raise ArgumentError, message
     end
-    private_class_method :_support_deprecated_option_paranoid
+    private_class_method :reject_nil_options
   end
 end

data/net-ssh.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |spec|
   spec.description   = %q{Net::SSH: a pure-Ruby implementation of the SSH2 client protocol. It allows you to write programs that invoke and interact with processes on remote servers, via SSH2.}
   spec.homepage      = "https://github.com/net-ssh/net-ssh"
   spec.license       = "MIT"
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.6")
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.7")
   spec.metadata = {
     "changelog_uri" => "https://github.com/net-ssh/net-ssh/blob/master/CHANGES.txt"
   }
@@ -30,18 +30,15 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  unless ENV['NET_SSH_NO_ED25519']
-    spec.add_development_dependency("bcrypt_pbkdf", "~> 1.0") unless RUBY_PLATFORM == "java"
-    spec.add_development_dependency("ed25519", "~> 1.2")
-    spec.add_development_dependency('x25519') unless RUBY_PLATFORM == 'java'
-  end
+  spec.add_dependency("logger")
+  spec.add_dependency("openssl", ">= 3.2.0")
 
-  spec.add_development_dependency('rbnacl', '~> 7.1') unless ENV['NET_SSH_NO_RBNACL']
+  spec.add_development_dependency("bcrypt_pbkdf", "~> 1.0") unless RUBY_PLATFORM == "java"
 
   spec.add_development_dependency "base64"
   spec.add_development_dependency "bundler", ">= 1.17"
   spec.add_development_dependency "minitest", "~> 5.19"
-  spec.add_development_dependency "mocha", "~> 2.1.0"
+  spec.add_development_dependency "mocha", ">= 2.1", "< 4"
   spec.add_development_dependency "ostruct"
   spec.add_development_dependency "rake", "~> 12.0"
   spec.add_development_dependency "rubocop", "~> 1.28.0"

data/rakelib/changelog.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'open3'
+
+# Builds CHANGES.txt sections from the fragment files in changelog.d/ (see CONTRIBUTING.md).
+class Changelog
+  class Error < StandardError; end
+
+  # Output order of the groups in a release section; `none` fragments are never emitted.
+  TYPES = {
+    'breaking-security' => 'BREAKING: Security: ',
+    'breaking' => 'BREAKING: ',
+    'security' => 'Security: ',
+    'change' => '',
+    'none' => nil
+  }.freeze
+
+  FILENAME = /\A(?<number>[1-9]\d*)\.(?<type>[a-z-]+)(?:\.(?<seq>[1-9]\d*))?\.txt\z/.freeze
+  REF = /#\d+|GHSA(?:-[a-z0-9]{4}){3}|CVE-\d{4}-\d+/i.freeze
+  REF_LIST = /\[(?:#{REF})(?:,\s*(?:#{REF}))*\]\z/.freeze
+  UNRELEASED = '=== Unreleased'
+  PLACEHOLDER = 'TODO: describe the change as it should read in CHANGES.txt'
+
+  Fragment = Struct.new(:path, :number, :type, :seq, :text) do
+    def entry
+      "#{TYPES.fetch(type)}#{text}"
+    end
+
+    def sort_key
+      [-number, seq]
+    end
+  end
+
+  attr_reader :dir, :changes_path
+
+  def initialize(root)
+    @root = root
+    @dir = File.join(root, 'changelog.d')
+    @changes_path = File.join(root, 'CHANGES.txt')
+  end
+
+  # Raises Error listing every invalid fragment; returns all fragments, including `none` ones.
+  def fragments
+    errors = []
+    fragments = []
+    entries_in_dir.each do |name|
+      result = parse_fragment(name)
+      result.is_a?(Fragment) ? fragments << result : errors << "changelog.d/#{name}: #{result}"
+    end
+    raise Error, "Invalid changelog fragments:\n  #{errors.join("\n  ")}" unless errors.empty?
+
+    fragments.sort_by(&:sort_key)
+  end
+
+  # Validates the fragments and the `=== Unreleased` section of CHANGES.txt; returns the fragments.
+  def check
+    all = fragments
+    split_changes(read_changes)
+    all
+  end
+
+  # The text of the section for +heading+, or nil for a pre-release with nothing to release.
+  def section(heading)
+    assemble(heading, fragments, split_changes(read_changes))
+  end
+
+  # Writes the section for +heading+ to the top of CHANGES.txt, folding in any `=== Unreleased`
+  # entries, and removes all fragments; returns the section, or nil when CHANGES.txt was left unchanged.
+  def release(heading)
+    all = fragments
+    content = read_changes
+    raise Error, "CHANGES.txt already has a '=== #{heading}' section" if content.lines.any? { |l| l.chomp == "=== #{heading}" }
+
+    parts = split_changes(content)
+    section = assemble(heading, all, parts)
+    if section
+      rest = parts[:rest].empty? ? '' : "\n#{parts[:rest]}"
+      File.write(changes_path, "#{parts[:preamble]}#{section}#{rest}")
+    end
+    remove(all.map(&:path))
+    section
+  end
+
+  # Creates a fragment for PR +number+ and returns its path; picks the next free `.N` suffix if needed.
+  def new_fragment(number, type, text = nil)
+    path = (1..).lazy.map { |seq| File.join(dir, fragment_name(number, type, seq)) }.find { |p| !File.exist?(p) }
+    error = validate_name(File.basename(path))
+    raise Error, error if error
+
+    FileUtils.mkdir_p(dir)
+    text = PLACEHOLDER if (text.nil? || text.strip.empty?) && type != 'none'
+    File.write(path, "#{text}\n")
+    path
+  end
+
+  def self.heading(major, minor, tiny, pre)
+    ["#{major}.#{minor}.#{tiny}", pre].compact.join(' ')
+  end
+
+  private
+
+  def entries_in_dir
+    return [] unless Dir.exist?(dir)
+
+    Dir.children(dir).sort.reject { |name| name == 'README.md' || name.start_with?('.') }
+  end
+
+  def fragment_name(number, type, seq)
+    seq == 1 ? "#{number}.#{type}.txt" : "#{number}.#{type}.#{seq}.txt"
+  end
+
+  def validate_name(name)
+    match = FILENAME.match(name)
+    return "file name must be <PR number>.<type>[.<n>].txt, types: #{TYPES.keys.join(', ')}" unless match
+    return "unknown type '#{match[:type]}', expected one of: #{TYPES.keys.join(', ')}" unless TYPES.key?(match[:type])
+
+    nil
+  end
+
+  # Returns a Fragment, or an error message.
+  def parse_fragment(name)
+    path = File.join(dir, name)
+    return 'is not a file' unless File.file?(path)
+
+    error = validate_name(name)
+    return error if error
+
+    match = FILENAME.match(name)
+    fragment = Fragment.new(path, match[:number].to_i, match[:type], (match[:seq] || 1).to_i, nil)
+    return fragment if fragment.type == 'none'
+
+    text = parse_text(read_utf8(path))
+    return text[:error] if text[:error]
+
+    fragment.text = text[:text]
+    fragment.text = "#{fragment.text} [##{fragment.number}]" unless fragment.text.match?(REF_LIST)
+    fragment
+  end
+
+  def parse_text(raw)
+    return { error: 'is not valid UTF-8' } unless raw.valid_encoding?
+
+    lines = raw.strip.lines.map(&:strip)
+    return { error: 'is empty' } if lines.empty?
+    return { error: 'must be a single paragraph (no blank lines)' } if lines.include?('')
+
+    text = lines.join(' ')
+    return { error: 'still contains the placeholder text' } if text == PLACEHOLDER
+    return { error: "should not start with a bullet, it's added when assembling" } if text.match?(/\A[*-] /)
+    return { error: 'should not start with BREAKING:/Security:, the type adds the prefix' } if text.match?(/\A(BREAKING|Security):/i)
+
+    { text: text }
+  end
+
+  def read_changes
+    File.exist?(changes_path) ? read_utf8(changes_path).gsub("\r\n", "\n") : ''
+  end
+
+  # Explicit so a non-UTF-8 locale (e.g. LANG=C) doesn't break on non-ASCII text.
+  def read_utf8(path)
+    File.read(path, mode: 'r:bom|utf-8')
+  end
+
+  # A final release (a heading without a pre-release suffix) always gets a section, so every published version has a heading.
+  def assemble(heading, fragments, parts)
+    entries = grouped_entries(fragments, parts[:unreleased])
+    if entries.empty?
+      return nil unless heading.match?(/\A\d+\.\d+\.\d+\z/)
+
+      previous = parts[:rest][/\A=== (.+)$/, 1]
+      entries = ["  * #{previous ? "No changes since #{previous}." : 'No changes.'}\n"]
+    end
+    "=== #{heading}\n\n#{entries.join}"
+  end
+
+  # Splits CHANGES.txt into the text before the first heading, the entries of a leading
+  # `=== Unreleased` section (as lists of raw lines) and everything from the first released heading on.
+  def split_changes(content)
+    lines = content.lines
+    first = lines.index { |l| l.start_with?('=== ') } || lines.size
+    preamble = lines[0...first].join
+    return { preamble: preamble, unreleased: [], rest: lines[first..].join } unless lines[first]&.chomp == UNRELEASED
+
+    body_end = lines.index.with_index { |l, i| i > first && l.start_with?('=== ') } || lines.size
+    { preamble: preamble, unreleased: unreleased_entries(lines[(first + 1)...body_end]), rest: lines[body_end..].join }
+  end
+
+  def unreleased_entries(lines)
+    lines.each_with_object([]) do |line, entries|
+      next if line.strip.empty?
+
+      if line.match?(/\A\s*\* /)
+        entries << [line]
+      elsif entries.empty?
+        raise Error, "Cannot parse the Unreleased section of CHANGES.txt near: #{line.strip}"
+      else
+        entries.last << line
+      end
+    end
+  end
+
+  # Fragments come before the hand-written Unreleased entries of the same group.
+  def grouped_entries(fragments, unreleased)
+    TYPES.keys.flat_map do |type|
+      from_fragments = fragments.select { |f| f.type == type && type != 'none' }.map { |f| "  * #{f.entry}\n" }
+      from_unreleased = unreleased.select { |lines| unreleased_type(lines.first) == type }.map do |lines|
+        lines.join.end_with?("\n") ? lines.join : "#{lines.join}\n"
+      end
+      from_fragments + from_unreleased
+    end
+  end
+
+  def unreleased_type(line)
+    text = line.sub(/\A\s*\* /, '')
+    TYPES.find { |_type, prefix| prefix && !prefix.empty? && text.start_with?(prefix) }&.first || 'change'
+  end
+
+  # `git rm` so the deletions are staged with the version bump; plain delete outside a git checkout.
+  def remove(paths)
+    return if paths.empty?
+
+    relative = paths.map { |p| p.delete_prefix("#{@root}/") }
+    _out, status = Open3.capture2e('git', '-C', @root, 'rm', '-q', '--', *relative)
+    FileUtils.rm_f(paths) unless status.success?
+  rescue SystemCallError
+    FileUtils.rm_f(paths)
+  end
+end