odysseus-core 0.3.2 → 0.9.0

data/lib/odysseus/setup/docker_apt.rb

@@ -0,0 +1,178 @@
+# lib/odysseus/setup/docker_apt.rb
+
+require 'shellwords'
+
+module Odysseus
+  module Setup
+    # Installs Docker from Docker's official apt repository, following Docker's
+    # published PROCEDURE for Ubuntu -- the keyring, the sources line, the apt
+    # install. Not its package list: see PACKAGES below, which deliberately
+    # omits docker-compose-plugin. Saying "following Docker's instructions"
+    # unqualified is what put the same overstatement on the docs site, where a
+    # reader deciding whether to run this was not told what would be missing.
+    #
+    # Every file this writes on the host is written WHOLE rather than appended,
+    # so a run interrupted anywhere leaves a stale file that the next run
+    # overwrites -- never a corrupt one with the repository listed twice.
+    #
+    # It repairs nothing it did not create: a broken dpkg state, a held lock, a
+    # third-party repository that fails to refresh are all reported and raised,
+    # not worked around. Guessing at someone else's apt state is how a bootstrap
+    # leaves a machine worse than it found it.
+    #
+    # The GPG key's fingerprint is deliberately not pinned. Pinning defends
+    # against a CA-level compromise of download.docker.com, but turns Docker's
+    # key rotation into an outage for everyone using this command; Docker's own
+    # instructions trust TLS, and so does this.
+    class DockerApt
+      KEYRING = '/etc/apt/keyrings/docker.asc'.freeze
+      SOURCES = '/etc/apt/sources.list.d/docker.list'.freeze
+      GPG_URL = 'https://download.docker.com/linux/ubuntu/gpg'.freeze
+      REPO_URL = 'https://download.docker.com/linux/ubuntu'.freeze
+      LOCK_FILE = '/var/lib/dpkg/lock-frontend'.freeze
+
+      # Long enough to outlast cloud-init and unattended-upgrades on a
+      # minutes-old host, which is the normal state of a machine someone is
+      # running setup against; short enough that a genuinely stuck lock is an
+      # error rather than a session that never returns.
+      LOCK_TIMEOUT = 300
+
+      # Deliberately short of Docker's published instructions, which also
+      # install docker-compose-plugin: nothing in this codebase invokes
+      # `docker compose`, odysseus runs containers through `docker run` /
+      # `docker create` (odysseus-core/lib/odysseus/docker/client.rb). Do not
+      # add it back on the strength of Docker's docs alone -- `setup` installs
+      # only what odysseus actually uses. docker-buildx-plugin stays: `docker
+      # buildx build` (odysseus-core/lib/odysseus/builder/client.rb:216) runs
+      # on the operator's own machine for the `:local` strategy, or on
+      # `builder.host` over SSH for `:remote` -- never on a deploy target as
+      # such, and setup's hosts come only from `servers.*`
+      # (odysseus-core/lib/odysseus/deployer/executor.rb:300-308). So on a
+      # host setup prepares, buildx is only reachable where `builder.host`
+      # happens to name one of those deploy hosts with multiarch on -- a
+      # coincidence plausible precisely in setup's single-host-trial niche,
+      # and worth keeping regardless: a modern `docker build` without the
+      # plugin falls back to Docker's deprecated legacy builder.
+      PACKAGES = %w[docker-ce docker-ce-cli containerd.io docker-buildx-plugin].freeze
+
+      # @param ssh [Odysseus::Deployer::SSH] connection as the bootstrap identity
+      # @param escalation [Odysseus::Setup::Escalation] how root is reached
+      # @param codename [String] Ubuntu's VERSION_CODENAME, e.g. "noble"
+      def initialize(ssh:, escalation:, codename:)
+        @ssh = ssh
+        @escalation = escalation
+        @codename = codename.to_s.strip
+      end
+
+      # @return [nil]
+      # @raise [Odysseus::SetupError] on any failure, with the apt output's
+      #   first line and, for a lock timeout, the process holding it
+      def install!
+        if @codename.empty?
+          raise Odysseus::SetupError,
+                '/etc/os-release reported no VERSION_CODENAME, so the apt repository line ' \
+                'cannot name a release. Refusing to guess one.'
+        end
+
+        apt('update')
+        apt('install -y ca-certificates curl')
+        make_keyring_dir
+        fetch_keyring
+        make_keyring_readable
+        write_sources
+        # The repository is only visible to apt after a refresh that follows
+        # the sources file, so this update is not the same as the one above.
+        apt('update')
+        apt("install -y #{PACKAGES.join(' ')}")
+
+        nil
+      end
+
+      private
+
+      def arch
+        @arch ||= @escalation.run('dpkg --print-architecture').to_s.strip
+      end
+
+      def sources_line
+        "deb [arch=#{arch} signed-by=#{KEYRING}] #{REPO_URL} #{@codename} stable"
+      end
+
+      # Every non-apt host call below is wrapped the same way #apt already
+      # is: a raw Odysseus::SSHCommandError from any of these used to escape
+      # #install! untouched, past Preparer#run_step's `rescue
+      # Odysseus::SetupError` and out of #prepare entirely -- reported by the
+      # CLI's per-host `rescue StandardError` as a step named :connection,
+      # discarding every step result that had already succeeded on that
+      # host. Wrapping here, at the point each command actually runs, is what
+      # keeps #install!'s own `@raise [Odysseus::SetupError] on any failure`
+      # true.
+
+      def make_keyring_dir
+        @escalation.run('install -m 0755 -d /etc/apt/keyrings')
+      rescue Odysseus::Error => e
+        raise Odysseus::SetupError,
+              "could not create /etc/apt/keyrings: #{e.message.lines.first.to_s.strip}"
+      end
+
+      # curl -o, not a redirect: the file is opened by the process sudo
+      # elevated, not by the bootstrap identity's own shell.
+      def fetch_keyring
+        @escalation.run("curl -fsSL #{GPG_URL} -o #{KEYRING}")
+      rescue Odysseus::Error => e
+        raise Odysseus::SetupError,
+              "could not download Docker's signing key from #{GPG_URL}: " \
+              "#{e.message.lines.first.to_s.strip}"
+      end
+
+      def make_keyring_readable
+        @escalation.run("chmod a+r #{KEYRING}")
+      rescue Odysseus::Error => e
+        raise Odysseus::SetupError,
+              "could not make #{KEYRING} readable: #{e.message.lines.first.to_s.strip}"
+      end
+
+      # `tee`, not `tee -a`: this file is replaced, not added to. The prefix
+      # goes on the writer alone via Escalation#elevate -- prefixing the whole
+      # pipeline would elevate printf and leave tee unprivileged, which is the
+      # defect that made setup's first authorized_keys append fail under the
+      # documented default identity.
+      def write_sources
+        writer = @escalation.elevate("tee #{Shellwords.escape(SOURCES)}")
+        @ssh.execute("printf '%s\n' #{Shellwords.escape(sources_line)} | #{writer} >/dev/null")
+      rescue Odysseus::Error => e
+        raise Odysseus::SetupError,
+              "could not write the apt sources file #{SOURCES}: #{e.message.lines.first.to_s.strip}"
+      end
+
+      # `env DEBIAN_FRONTEND=noninteractive` rather than a bare assignment:
+      # sudoers may refuse to pass an environment variable through, and a
+      # prompt cannot be answered on a non-interactive connection at all.
+      def apt(args)
+        @escalation.run(
+          "env DEBIAN_FRONTEND=noninteractive apt-get -o DPkg::Lock::Timeout=#{LOCK_TIMEOUT} #{args}"
+        )
+      rescue Odysseus::Error => e
+        raise Odysseus::SetupError,
+              "apt-get #{args.split.first} failed#{lock_holder_note}: " \
+              "#{e.message.lines.first.to_s.strip}"
+      end
+
+      # Best-effort attribution, never a second failure: if fuser or ps is
+      # missing the message simply says less.
+      def lock_holder_note
+        # fuser can report more than one holder as space-separated PIDs on
+        # one line. `tr -d ' '` would glue them into one fabricated number --
+        # "1234 5678" becoming "12345678" -- so take the first token instead
+        # of deleting every space.
+        pid = @escalation.run("fuser #{LOCK_FILE} 2>/dev/null").to_s.strip.split.first.to_s
+        return '' if pid.empty?
+
+        name = @escalation.run("ps -o comm= -p #{Shellwords.escape(pid)} 2>/dev/null || true").to_s.strip
+        name.empty? ? " (pid #{pid} holds #{LOCK_FILE})" : " (#{name}, pid #{pid}, holds #{LOCK_FILE})"
+      rescue Odysseus::Error
+        ''
+      end
+    end
+  end
+end

data/lib/odysseus/setup/escalation.rb

@@ -0,0 +1,73 @@
+# lib/odysseus/setup/escalation.rb
+
+module Odysseus
+  module Setup
+    # How `odysseus setup` gets root on the host it is preparing.
+    #
+    # The bootstrap identity is named by --as and defaults to `ubuntu`, so
+    # needing sudo is the common path rather than the exception: Ubuntu's LTS
+    # cloud images ship that user with passwordless sudo already configured.
+    # A root bootstrap must not touch sudo at all — minimal images often do not
+    # have it installed.
+    #
+    # The probe exists because a sudo password prompt cannot be answered:
+    # Net::SSH runs with non_interactive: true, so a prompt hangs and then
+    # fails with nothing useful said. Asking up front turns that into one
+    # sentence before anything has been changed.
+    class Escalation
+      ROOT = 'root'.freeze
+
+      # @param ssh [Odysseus::Deployer::SSH] connection as the bootstrap identity
+      # @param as [String] that identity's username
+      def initialize(ssh:, as:)
+        @ssh = ssh
+        @as = as
+      end
+
+      # @return [Boolean] whether commands need a sudo prefix
+      def sudo?
+        @as != ROOT
+      end
+
+      # @raise [Odysseus::SetupError] when escalation is not available
+      def probe!
+        return unless sudo?
+
+        @ssh.execute('sudo -n true')
+      # SSHCommandError only, deliberately: it is the one that means the
+      # command ran and sudo said no. Its sibling SSHConnectionError -- and
+      # everything else under Odysseus::Error -- means the host was never
+      # reached, and this is the FIRST command setup sends, so an unreachable
+      # host arrives here before anywhere else. Rescuing the shared ancestor
+      # told an operator whose DNS was wrong, or whose host was down, to go
+      # configure NOPASSWD sudo. A connection failure travels on untouched,
+      # to be reported against the connection by the caller that owns it.
+      rescue Odysseus::SSHCommandError => e
+        raise Odysseus::SetupError,
+              "#{@as} cannot escalate with passwordless sudo, which odysseus setup requires: " \
+              "#{e.message.lines.first.to_s.strip}. Odysseus cannot answer a password prompt. " \
+              'Use --as root on a host where root can log in, or give this user NOPASSWD sudo.'
+      end
+
+      # The one place that decides whether a command needs a sudo prefix.
+      # Exposed rather than kept inside #run because a command whose
+      # privileged half is only *part* of a pipeline cannot go through #run:
+      # `sudo -n printf ... | tee file` would elevate printf and leave tee
+      # unprivileged, which is the defect that made the first authorized_keys
+      # append fail under the documented default identity. Callers in that
+      # position build the pipeline themselves and elevate the writer alone.
+      #
+      # @param command [String] a command that needs root
+      # @return [String] it, prefixed when a prefix is needed
+      def elevate(command)
+        sudo? ? "sudo -n #{command}" : command
+      end
+
+      # @param command [String] a command that needs root
+      # @return [String] its output
+      def run(command)
+        @ssh.execute(elevate(command))
+      end
+    end
+  end
+end

data/lib/odysseus/setup/preparer.rb

@@ -0,0 +1,372 @@
+# lib/odysseus/setup/preparer.rb
+
+require 'shellwords'
+
+module Odysseus
+  module Setup
+    # Prepares a fresh host so odysseus can deploy to it as a non-root user.
+    #
+    # Runs over the connection made as the bootstrap identity (--as, root or
+    # otherwise) and escalates through `escalation` for anything that touches
+    # host state. Each step checks before it acts, so a second run against an
+    # already-prepared host changes nothing and every step reports :ok — the
+    # first run, mid-preparation, is the one that should say :changed.
+    #
+    # Docker is installed from Docker's own apt repository when the host does
+    # not have it (see DockerApt); a host whose daemon still does not answer
+    # afterwards fails the step rather than being handed back half-prepared.
+    class Preparer
+      SUPPORTED_UBUNTU = %w[24.04 26.04].freeze
+
+      # @param step [Symbol] which step this is
+      # @param status [Symbol] :ok, :changed, :warn or :fail
+      # @param detail [String] one line a reader can act on
+      Result = Data.define(:step, :status, :detail)
+
+      # @param ssh [Odysseus::Deployer::SSH] connection as the bootstrap identity
+      # @param config [Hash] parsed deploy.yml; only ssh.user is read here
+      # @param escalation [Odysseus::Setup::Escalation] how root is reached
+      # @param keys [Array<String>] resolved authorized_keys lines (see
+      #   Odysseus::Setup::PublicKey.resolve, which the caller has already run)
+      def initialize(ssh:, config:, escalation:, keys:)
+        @ssh = ssh
+        @config = config
+        @escalation = escalation
+        @keys = keys
+        @user = config.dig(:ssh, :user)
+        @home_dir = nil
+      end
+
+      # @return [Array<Result>] one per step that ran, in a stable order.
+      #   A :fail halts the sequence — nothing after a failed gate is safe to
+      #   attempt, whether that's an unsupported distro or a missing daemon.
+      def prepare
+        results = [escalation_step]
+        return results if results.last.status == :fail
+
+        %i[distro docker user group keys state_dir self_test].each do |step|
+          result = run_step(step)
+          results << result
+          break if result.status == :fail
+        end
+
+        results
+      end
+
+      private
+
+      # Any step from :user onward can raise Odysseus::SetupError now:
+      # #resolve_home_dir refuses to guess an unresolved home rather than
+      # silently building a path out of it (see #home_dir). That refusal
+      # needs to be attributed to the step that hit it, the same way
+      # escalation_step already converts its own SetupError into a Result
+      # rather than letting a raise crash #prepare outright -- this is that
+      # same conversion, applied once here instead of duplicated in every
+      # step that touches home_dir.
+      def run_step(step)
+        send(:"#{step}_step")
+      rescue Odysseus::SetupError => e
+        Result.new(step: step, status: :fail, detail: e.message)
+      end
+
+      def escalation_step
+        @escalation.probe!
+        detail = @escalation.sudo? ? 'passwordless sudo confirmed' : 'connected as root'
+        Result.new(step: :escalation, status: :ok, detail: detail)
+      rescue Odysseus::SetupError => e
+        Result.new(step: :escalation, status: :fail, detail: e.message)
+      end
+
+      # No escalation: /etc/os-release is world-readable, and the gate itself
+      # must hold even on a host escalation cannot yet be proven on.
+      def distro_step
+        os = read_os_release
+        id = os['ID']
+        version = os['VERSION_ID']
+
+        if id == 'ubuntu' && SUPPORTED_UBUNTU.include?(version)
+          Result.new(step: :distro, status: :ok, detail: "ubuntu #{version}")
+        else
+          Result.new(
+            step: :distro, status: :fail,
+            detail: "#{id || 'unknown'} #{version} — odysseus setup only knows " \
+                    "ubuntu #{SUPPORTED_UBUNTU.join(' or ')}"
+          )
+        end
+      end
+
+      # Check, then install, then check again. The second probe is the only
+      # thing that decides success: apt exiting 0 says a package was unpacked,
+      # not that a daemon answers, and it is the daemon every deploy needs.
+      def docker_step
+        version = docker_version
+        return Result.new(step: :docker, status: :ok, detail: "docker #{version}") if version
+
+        DockerApt.new(ssh: @ssh, escalation: @escalation, codename: read_os_release['VERSION_CODENAME']).install!
+
+        version = docker_version
+        unless version
+          return Result.new(
+            step: :docker, status: :fail,
+            detail: 'installed docker from apt, but its daemon still does not answer. ' \
+                    'The host may need a reboot, or the daemon may have failed to start.'
+          )
+        end
+
+        Result.new(step: :docker, status: :changed, detail: "installed docker #{version}")
+      end
+
+      # @return [String, nil] the running daemon's version, or nil if it does
+      #   not answer -- which does not distinguish "not installed" from
+      #   "installed, stopped", and does not need to: both are a host without
+      #   a usable Docker until this step has run.
+      def docker_version
+        output = @escalation.run("docker info --format '{{.ServerVersion}}' 2>&1 || true").to_s.strip
+        output.match?(/\A\d+\./) ? output : nil
+      end
+
+      def user_step
+        if user_exists?
+          verify_home_ownership
+        else
+          @escalation.run("useradd --create-home --shell /bin/bash #{shell_user}")
+          Result.new(step: :user, status: :changed, detail: "created #{@user}, home #{home_dir}")
+        end
+      end
+
+      def user_exists?
+        !@escalation.run("id -u #{shell_user} 2>/dev/null || true").to_s.strip.empty?
+      end
+
+      # Repairs ownership, and only ownership: this never touches the shell,
+      # the password, or anything else about a user odysseus did not create.
+      #
+      # The user existing does not guarantee the home does: useradd normally
+      # creates both together, but a user made some other way, or one whose
+      # home was removed after the fact, can exist without one. `chown` on a
+      # path that isn't there raises rather than repairing anything, so the
+      # directory is created first -- a no-op when it already exists -- which
+      # is the actual "half-created-user recovery" the brief names, not just
+      # the ownership half of it.
+      def verify_home_ownership
+        @escalation.run("mkdir -p #{Shellwords.escape(home_dir)}") unless dir_present?(home_dir)
+        owner, group = @escalation.run("stat -c '%U %G' #{Shellwords.escape(home_dir)} 2>/dev/null || true").to_s.split
+
+        if owner == @user && group == @user
+          Result.new(step: :user, status: :ok, detail: "#{@user} exists, home owned correctly")
+        else
+          @escalation.run("chown #{shell_user}:#{shell_user} #{Shellwords.escape(home_dir)}")
+          detail = "repaired #{home_dir} (was #{owner || 'missing'} #{group || 'missing'})"
+          Result.new(step: :user, status: :changed, detail: detail)
+        end
+      end
+
+      def group_step
+        groups = @escalation.run("id -nG #{shell_user} 2>/dev/null || true").to_s.split
+
+        if groups.include?('docker')
+          Result.new(step: :group, status: :ok, detail: "#{@user} is in the docker group")
+        else
+          @escalation.run("usermod -aG docker #{shell_user}")
+          Result.new(step: :group, status: :changed, detail: "added #{@user} to the docker group")
+        end
+      end
+
+      # Never overwrites: a second operator's key installed by an earlier run
+      # must survive this one. Only the keys actually missing are appended,
+      # and the directory is only touched (mkdir/chmod/chown) when something
+      # needs to change — a healthy re-run issues none of those commands.
+      def keys_step
+        missing = @keys.reject { |line| key_present?(line) }
+        return Result.new(step: :keys, status: :ok, detail: "#{@keys.size} key(s) already present") if missing.empty?
+
+        @escalation.run("mkdir -p #{Shellwords.escape(ssh_dir)}")
+        @escalation.run("touch #{Shellwords.escape(authorized_keys)}")
+        missing.each { |line| append_key(line) }
+        # 700/600 are reapplied every time a key is appended, so a directory
+        # left loose is corrected as a side effect of appending a key — sshd
+        # ignores both silently, with no error worth finding. Only a side
+        # effect, though: this step early-returns above when every key is
+        # already present, so a pre-existing world-writable ~/.ssh on an
+        # otherwise fully up-to-date host is never revisited or repaired.
+        @escalation.run("chmod 700 #{Shellwords.escape(ssh_dir)}")
+        @escalation.run("chmod 600 #{Shellwords.escape(authorized_keys)}")
+        @escalation.run("chown -R #{shell_user}:#{shell_user} #{Shellwords.escape(ssh_dir)}")
+
+        Result.new(step: :keys, status: :changed, detail: "added #{missing.size} key(s)")
+      end
+
+      # A `>>` redirect is set up by the CONNECTION's own shell before sudo
+      # ever runs -- sudo only elevates the command it's given, not the
+      # shell that's about to open a file for it. `sudo -n echo line >>file`
+      # therefore tries to open `file` as the *bootstrap* identity, which
+      # cannot write into another user's authorized_keys and fails outright
+      # under the documented default of --as ubuntu. Piping into `tee -a`
+      # instead keeps the open() inside the process that's actually
+      # escalated, which is the standard idiom for exactly this reason.
+      # Nothing here needs escalation at all under --as root, so the prefix is
+      # applied to the writer alone and only when needed -- via
+      # Escalation#elevate, so this is not a second opinion about when sudo is
+      # required.
+      def append_key(line)
+        writer = @escalation.elevate("tee -a #{Shellwords.escape(authorized_keys)}")
+        @ssh.execute("printf '%s\n' #{Shellwords.escape(line)} | #{writer} >/dev/null")
+      end
+
+      def key_present?(line)
+        cmd = "grep -qxF #{Shellwords.escape(line)} #{Shellwords.escape(authorized_keys)} 2>/dev/null && echo present || echo absent"
+        @escalation.run(cmd).to_s.strip == 'present'
+      end
+
+      def state_dir_step
+        dir = state_dir
+        exists = dir_present?(dir)
+        owner = exists ? @escalation.run("stat -c '%U' #{Shellwords.escape(dir)} 2>/dev/null || true").to_s.strip.split.first : nil
+
+        if exists && owner == @user
+          Result.new(step: :state_dir, status: :ok, detail: "#{dir} exists")
+        else
+          @escalation.run("mkdir -p #{Shellwords.escape(dir)}")
+          @escalation.run("chown #{shell_user}:#{shell_user} #{Shellwords.escape(dir)}")
+          Result.new(step: :state_dir, status: :changed, detail: "created #{dir}")
+        end
+      end
+
+      # A genuinely fresh connection, authenticated as the deploy user rather
+      # than the bootstrap identity -- reusing @ssh would only prove @user's
+      # own access, over a session that may predate the docker-group change
+      # (usermod -aG only takes effect for new logins) and against a home
+      # directory @ssh's identity typically cannot even read into. no sudo
+      # here either way: this is the proof the host is usable with no help
+      # from escalation, which is the whole safety argument for the command.
+      # Because it never writes anything, a failure here leaves the bootstrap
+      # path -- and everything already prepared -- untouched and the host
+      # still reachable. A failure to even log in is reported by name rather
+      # than left to propagate, since that is the bricked-host case this step
+      # exists to catch before odysseus hands the host back.
+      def self_test_step
+        dir = state_dir
+        fresh = Odysseus::Deployer::SSH.new(
+          host: @ssh.host,
+          user: @user,
+          port: @ssh.port,
+          keys: @config.dig(:ssh, :keys) || [],
+          use_tailscale: false
+        )
+
+        begin
+          docker_output = fresh.execute("docker info --format '{{.ServerVersion}}' 2>&1 || true").to_s.strip
+          docker_ok = docker_output.match?(/\A\d+\./)
+          writable = fresh.execute(
+            "test -d #{Shellwords.escape(dir)} && test -w #{Shellwords.escape(dir)} && echo present || echo absent"
+          ).to_s.strip == 'present'
+
+          if docker_ok && writable
+            Result.new(step: :self_test, status: :ok, detail: "docker and #{dir} reachable as #{@user}")
+          else
+            problems = []
+            problems << 'docker did not answer' unless docker_ok
+            problems << "#{dir} is not writable" unless writable
+            Result.new(step: :self_test, status: :fail, detail: problems.join('; '))
+          end
+        rescue Odysseus::Error => e
+          Result.new(
+            step: :self_test, status: :fail,
+            detail: "could not log in as #{@user}: #{e.message.lines.first.to_s.strip}"
+          )
+        ensure
+          fresh.close
+        end
+      end
+
+      def dir_present?(dir)
+        @escalation.run("test -d #{Shellwords.escape(dir)} && echo present || echo absent").to_s.strip == 'present'
+      end
+
+      def read_os_release
+        @read_os_release ||= begin
+          raw = @ssh.execute('cat /etc/os-release 2>/dev/null || true').to_s
+
+          raw.lines.each_with_object({}) do |line, acc|
+            key, value = line.strip.split('=', 2)
+            next if key.nil? || value.nil?
+
+            acc[key] = value.delete('"')
+          end
+        end
+      end
+
+      # Ubuntu's useradd defaults HOME=/home, but that only holds for a user
+      # this class creates itself. A pre-existing user can have any home at
+      # all -- assuming /home/<user> for one installs keys and a state
+      # directory where sshd never reads them, while still reporting
+      # success. Read it from the host instead, once the user is known to
+      # exist, and memoize it: a second call must not re-ask a question
+      # that cannot have changed mid-run.
+      def home_dir
+        @home_dir ||= resolve_home_dir
+      end
+
+      # No pipe: a pipeline's exit status is its LAST command's, so
+      # `getent passwd <user> | cut -d: -f6` used to exit 0 with empty
+      # output no matter how badly getent itself failed -- the third
+      # instance on this branch of the exit status being observed not
+      # being the one that mattered. getent's own exit status decides now,
+      # via @escalation.run's ordinary raise-on-failure; field 6 is split
+      # out in Ruby instead of by a second process.
+      #
+      # The result is validated before it is ever used to build a path.
+      # File.join("", ".ssh") is "/.ssh" -- a blank answer would let
+      # keys_step and state_dir_step succeed at the filesystem root while
+      # /home/<user> is never touched, reporting a host ready when
+      # authorized_keys was never written there. An answer of exactly "/"
+      # is worse: verify_home_ownership would find it "owned wrong" and
+      # `chown` it straight to the deploy user, seizing a directory setup
+      # never created -- the same invariant Finding 1 exists to protect,
+      # lost the moment an arbitrary passwd field replaced the old,
+      # effectively sandboxed /home/<user> join. There is no safe
+      # fallback to substitute: a guess is what caused this, so an
+      # unresolved home fails the step that needed it, by name, instead.
+      def resolve_home_dir
+        candidate = @escalation.run("getent passwd #{shell_user}").to_s.strip.split(':')[5].to_s.strip
+
+        if candidate.start_with?('/')
+          # Squeeze BEFORE expanding, not after: POSIX makes a path that
+          # starts with exactly two slashes implementation-defined, so
+          # File.expand_path leaves "//" as "//" rather than folding it to
+          # "/" -- expand_path alone would still accept the very spelling
+          # that reached verify_home_ownership's `chown` unrejected. Once
+          # collapsed to a single leading slash, expand_path also resolves
+          # "/." and "/.." (both the filesystem root by another spelling)
+          # down to "/", where the check below catches them too. This is
+          # pure string manipulation on an already-absolute path -- no
+          # symlink resolution, nothing touches the machine running
+          # odysseus, only the string describing a path on the remote host.
+          canonical = File.expand_path(candidate.sub(%r{\A/+}, '/'))
+          return canonical unless canonical == '/'
+        end
+
+        raise Odysseus::SetupError,
+              "could not resolve a home directory for #{@user}: getent passwd reported " \
+              "#{candidate.empty? ? 'nothing usable' : candidate.inspect} for it. Refusing " \
+              'to guess /home/<user> in its place.'
+      end
+
+      def ssh_dir
+        File.join(home_dir, '.ssh')
+      end
+
+      def authorized_keys
+        File.join(ssh_dir, 'authorized_keys')
+      end
+
+      def state_dir
+        File.join(home_dir, Odysseus::HostPaths::USER_DIRNAME)
+      end
+
+      def shell_user
+        Shellwords.escape(@user)
+      end
+    end
+  end
+end