samagotchi 0.129.0 → 0.130.0

data/lib/samagotchi/guardrails/child_boundary.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "outside"
-require_relative "protected_paths"
+require_relative "path_resolve"
 require_relative "shell_lex"
 require_relative "shell_paths"
 require_relative "shared_git"
@@ -88,8 +88,8 @@ module Samagotchi
       # repository (and not into root, which may sit inside the main one),
       # under chi's env or the call's env: (Targets#shell_envs).
       def names_other_checkout?(targets, root)
-        real_root = ProtectedPaths.real(root)
-        others = [*@worktrees.call, @common_dir.call].compact.map { |dir| ProtectedPaths.real(dir) } - [real_root]
+        real_root = PathResolve.real(root)
+        others = [*@worktrees.call, @common_dir.call].compact.map { |dir| PathResolve.real(dir) } - [real_root]
         return false if others.empty?
 
         commands = ShellLex.simple_commands(ShellLex.lex(targets.command.to_s))
@@ -99,8 +99,8 @@ module Samagotchi
             walk.step(words).any? do |_word, path|
               next false unless path
 
-              ProtectedPaths.reals(path).any? do |real|
-                !ShellPaths.within?(real, real_root) && others.any? { |dir| ShellPaths.within?(real, dir) }
+              PathResolve.reals(path).any? do |real|
+                !PathResolve.under?(real, real_root) && others.any? { |dir| PathResolve.under?(real, dir) }
               end
             end
           end

data/lib/samagotchi/guardrails/outside.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
 require "pathname"
-require "tmpdir"
-require_relative "protected_paths"
+require_relative "path_resolve"
 require_relative "../memory_bundle/index_sync"
 
 module Samagotchi
@@ -20,17 +19,18 @@ module Samagotchi
     # A path whose landing place resolving can't tell (.resolve: a dangling
     # symlink, a file with another hard link) is always outside.
     module Outside
-      TMP_DIRS = %w[/tmp /var/tmp].freeze
+      TMP_DIRS = PathResolve::TMP_DIRS
 
       # @param path [String] absolute
       # @param root [String] the session's repo root (or cwd)
       def self.outside?(path, root:)
         reals = resolve(path) or return true
-        session = ProtectedPaths.real(root)
+        session = PathResolve.real(root)
+        tmp = nil
         reals.any? do |real|
           next false if within?(real, session)
           next false if MemoryBundle::IndexSync.memory_scope(path)
-          next false if tmp_roots.any? { |tmp| within?(real, tmp) && !within?(session, tmp) }
+          next false if (tmp ||= session_tmp_roots(session)).any? { |dir| within?(real, dir) }
 
           true
         end
@@ -44,7 +44,7 @@ module Samagotchi
       # @param root [String] the session's project root
       def self.inside?(path, root:)
         reals = resolve(path) or return false
-        session = ProtectedPaths.real(root)
+        session = PathResolve.real(root)
         reals.all? { |real| within?(real, session) }
       end
 
@@ -55,15 +55,16 @@ module Samagotchi
       # @param root [String] the session's repo root (or cwd)
       def self.tmp_write?(path, root:)
         reals = resolve(path) or return false
-        session = ProtectedPaths.real(root)
-        reals.all? { |real| tmp_roots.any? { |tmp| within?(real, tmp) && !within?(session, tmp) } }
+        session = PathResolve.real(root)
+        tmp = session_tmp_roots(session)
+        reals.all? { |real| tmp.any? { |dir| within?(real, dir) } }
       end
 
-      # +path+ resolved (ProtectedPaths.reals: the lexical answer and where
+      # +path+ resolved (PathResolve.reals: the lexical answer and where
       # the kernel lands, a `..` after a symlinked dir climbing out of its
       # target), or nil when that doesn't say where a write lands: the path
       # is or goes through a dangling symlink (a write would create its
-      # target; ProtectedPaths.real follows it, the lexical answer stops at
+      # target; PathResolve.real follows it, the lexical answer stops at
       # it, and either way the link's own place doesn't count as where the
       # file is), or is a file with another hard link (a write would change
       # that file too). Both outside? and tmp_write? read it, so neither
@@ -71,7 +72,7 @@ module Samagotchi
       # @param path [String] absolute
       # @return [Array<String>, nil]
       def self.resolve(path)
-        reals = ProtectedPaths.reals(path)
+        reals = PathResolve.reals(path)
         return nil if reals.any? { |real| Pathname.new(real).ascend.any?(&:symlink?) }
         return nil if reals.any? { |real| File.file?(real) && File.stat(real).nlink > 1 }
 
@@ -80,16 +81,17 @@ module Samagotchi
         nil
       end
 
-      # The tmp dirs that exist, resolved.
-      def self.tmp_roots
-        [Dir.tmpdir, *TMP_DIRS].filter_map do |dir|
-          File.realpath(dir) if File.directory?(dir)
-        rescue SystemCallError
-          nil
-        end.uniq
-      end
+      # The tmp dirs that exist, resolved (PathResolve.tmp_roots).
+      def self.tmp_roots = PathResolve.tmp_roots
+
+      # The tmp dirs +session+ (resolved) isn't in (PathResolve.tmp_roots).
+      def self.session_tmp_roots(session) = PathResolve.tmp_roots(session: session, roots: tmp_roots)
 
-      def self.within?(path, root) = path == root || path.start_with?(File.join(root, ""))
+      # Whether +path+ is +root+ or in it (PathResolve.under?): cased alike
+      # on a disk that folds case when +root+ exists (resolved, it has its
+      # on-disk case), by their exact text when it doesn't (a missing root
+      # keeps the case it was typed in).
+      def self.within?(path, root) = PathResolve.under?(path, root, fold: File.exist?(root))
     end
   end
 end

data/lib/samagotchi/guardrails/pair_boundary.rb

@@ -25,7 +25,9 @@ module Samagotchi
     #     read or written (read, write, edit, a plugin's targets: paths), and
     #     on what a command does (execute, and any call whose targets carry
     #     a command: PairCommand, which also refuses chi and chi web on a
-    #     loopback name, background and scheduled jobs, the environment and
+    #     loopback name, URL openers (open, xdg-open, a browser) and
+    #     listeners (nc -l, socat …LISTEN, a static HTTP server), background
+    #     and scheduled jobs, the environment and
     #     credential printers, git settings that run commands, home sweeps
     #     and links to them, and a program named by a $var or a glob); a
     #     write or edit of git's hooks (GIT_HOOKS);
@@ -78,8 +80,17 @@ module Samagotchi
       GIT_CONFIG = "a participant's turn can't change git's global config or set what makes git run a command " \
                    "(core.hooksPath, core.fsmonitor, core.sshCommand, core.pager, core.editor, ! aliases)"
       GIT_HOOKS = "a participant's turn can't write git's hooks (.git/hooks): git runs them in the owner's name"
-      CHI_WEB = "a participant's turn can't call chi web on this machine: on loopback it answers as the owner " \
-                "(sessions, shares, answers)"
+      # chi web on loopback asks the owner's token too (Web::App#token_gate,
+      # LAN mode); this text check stays as defense in depth: a loopback-only
+      # chi web still answers loopback as the owner.
+      CHI_WEB = "a participant's turn can't call chi web on this machine: it is the owner's (sessions, shares, answers)"
+      # A page opened in the owner's browser carries the owner's cookies
+      # (chi web's on 127.0.0.1 or the LAN address among them) to whatever
+      # it points at; a port listening here could catch them.
+      OPENER = "a participant's turn can't open a URL or a file in the owner's apps: a browser sends that page the " \
+               "owner's cookies"
+      LISTENER = "a participant's turn can't listen on a port: what it serves on this machine could catch the " \
+                 "owner's browser cookies"
       VERB = "a participant's turn runs only a program named plainly: no $, $(…) or glob in a command's name"
       UNREADABLE = "a participant's turn runs only commands chi can read: split this command, or write the file " \
                    "with the write tool"

data/lib/samagotchi/guardrails/pair_command.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "outside"
+require_relative "path_resolve"
 require_relative "read_only_shell"
 require_relative "review_paths"
 require_relative "shell_paths"
@@ -11,7 +12,8 @@ module Samagotchi
     # One shell command of a participant's pair turn, read the way
     # PairBoundary needs it (the refusal words are PairBoundary's):
     # - #refusal: why it may not run, nil when it may: chi, something left
-    #   running, the environment or the keychain, git settings that run
+    #   running, a URL opener or a listener (OPENERS, LISTENERS: the owner's
+    #   browser cookies), the environment or the keychain, git settings that run
     #   commands, a folder sweep, a secret (a path a word resolves to, a glob
     #   or a $var whose fixed part leads into one, SECRET_TEXT for the
     #   rest); a script it hands a shell (sh -c, eval, a heredoc) is read as
@@ -66,6 +68,24 @@ module Samagotchi
       # A credential helper run by itself (docker-credential-osxkeychain get).
       CREDENTIAL_HELPER = /\A(?:docker-credential-|git-credential-)/
       ENV_TEXT = %r{/proc/[^\s]*/environ}
+      # Programs that open a URL or a file in the owner's apps (a browser
+      # sends the owner's cookies with it), whatever their arguments; gio
+      # with its open verb.
+      OPENERS = %w[open xdg-open gnome-open kde-open kde-open5 kfmclient exo-open wslview sensible-browser
+                   x-www-browser www-browser google-chrome google-chrome-stable chromium chromium-browser
+                   firefox safari msedge microsoft-edge brave-browser].freeze
+      # Programs that listen on a port whatever their arguments (static
+      # HTTP servers), and the netcats, which listen with -l.
+      LISTENERS = %w[http-server live-server httpd lighttpd nginx caddy miniserve darkhttpd webfsd].freeze
+      NETCATS = %w[nc ncat netcat].freeze
+      NC_LISTEN = /\A-[a-zA-Z0-9]*l|\A--listen\z/
+      # An interpreter's flags or arguments that serve a port (python -m
+      # http.server, ruby -run -e httpd, php -S, busybox httpd).
+      SERVE_MODULES = %w[http.server SimpleHTTPServer CGIHTTPServer socketserver].freeze
+      # An interpreter's script that opens a URL in the owner's apps, or
+      # listens on a port.
+      SCRIPT_OPENER_TEXT = /\bwebbrowser\b|\bopen location\b|openExternal|xdg-open|\bopen\s+["']?https?:/
+      SCRIPT_LISTEN_TEXT = /\blisten\s*\(|\bhttp\.server\b|\bserve_forever\b|HTTPServer|TCPServer|socketserver|createServer|WEBrick|\bhttpd\b/
       # This machine's loopback names (.web_text): localhost and its
       # subdomains, 127.x.y.z, 0.0.0.0, ::1 spelt any way, ::ffff:127.x.
       LOOPBACK_HOSTS = [/(?:[\w-]+\.)*localhost\.?/, /127(?:\.\d{1,3}){1,3}/, /0\.0\.0\.0/,
@@ -89,6 +109,9 @@ module Samagotchi
       GIT_VALUE_OPTIONS = %w[-C --git-dir --work-tree --namespace --exec-path].freeze
       # Devices a command may name in the project's stead.
       DEVICES = %w[/dev/null /dev/stdout /dev/stderr /dev/tty /dev/zero /dev/random /dev/urandom].freeze
+      # A word that starts with $TMPDIR or ${TMPDIR}.
+      TMPDIR_WORD = /\A\$(?:\{TMPDIR\}|TMPDIR\b)/
+
       # A path in a script's text (an interpreter's -e/-c, a heredoc): ~, ..
       # or an absolute path, at the text's start or after a space, quote,
       # bracket, = or comma.
@@ -120,7 +143,7 @@ module Samagotchi
       # (ShellPaths::HOOKS_PART): git runs what is there.
       def self.git_hook?(path)
         path.to_s.match?(ShellPaths::HOOKS_PART) ||
-          (path.to_s.start_with?("/") && ProtectedPaths.reals(path).any? { |real| real.match?(ShellPaths::HOOKS_PART) })
+          (path.to_s.start_with?("/") && PathResolve.reals(path).any? { |real| real.match?(ShellPaths::HOOKS_PART) })
       end
 
       # A command's text naming chi web's endpoint on this machine: a
@@ -236,10 +259,34 @@ module Samagotchi
         return PairBoundary::BACKGROUND if upto.any? { |w| DETACHERS.include?(File.basename(w)) } || detached_session?(program, args)
         return PairBoundary::ENVIRONMENT if env_reader?(program, args) || bare_env?(words)
         return PairBoundary::GIT_CONFIG if program == "git" && git_runs_commands?(args)
+        return PairBoundary::OPENER if opener?(program, args)
+        return PairBoundary::LISTENER if listener?(program, args)
 
         nil
       end
 
+      # open, xdg-open, a browser, gio open; osascript's open location is
+      # its script's (#script_text_refusal).
+      def opener?(program, args)
+        OPENERS.include?(program.to_s.downcase) || (program == "gio" && args.first == "open")
+      end
+
+      # nc -l, socat with a …LISTEN address, a static HTTP server, an
+      # interpreter serving a module (python -m http.server), ruby's un
+      # httpd (ruby -run -e httpd, ruby being a wrapper word: the args are
+      # the whole command's), php -S, busybox httpd.
+      def listener?(program, args)
+        name = program.to_s
+        return true if LISTENERS.include?(name)
+        return true if NETCATS.include?(name) && args.any? { |arg| arg.match?(NC_LISTEN) }
+        return true if name == "socat" && args.any? { |arg| arg.match?(/LISTEN/i) }
+        return true if name.start_with?("php") && args.include?("-S")
+        return true if name == "busybox" && args.first == "httpd"
+        return true if args.each_cons(2).any? { |flag, value| flag == "-m" && SERVE_MODULES.include?(value) }
+
+        false
+      end
+
       # A program word the shell expands: a $var, a $(…), a glob (bin/ch?,
       # ${e}i); the test brackets and braces are words of their own.
       def unplain_program?(word)
@@ -297,6 +344,8 @@ module Samagotchi
         return PairBoundary::SECRET if script.match?(PairBoundary::SECRET_TEXT)
         return PairBoundary::ENVIRONMENT if script.match?(SCRIPT_ENV_TEXT) || script.match?(ENV_TEXT)
         return PairBoundary::BACKGROUND if script.match?(SCRIPT_BACKGROUND_TEXT)
+        return PairBoundary::OPENER if script.match?(SCRIPT_OPENER_TEXT)
+        return PairBoundary::LISTENER if script.match?(SCRIPT_LISTEN_TEXT)
 
         nil
       end
@@ -413,12 +462,16 @@ module Samagotchi
 
       # A word Walk can't resolve: a glob checked by what it matches and by
       # its fixed part, a $var by its fixed part (the text before the first
-      # glob character or $, with ~ and $HOME expanded). A script body
-      # (spaces, quotes), a data heredoc or a $(…) is left to the other checks.
+      # glob character or $, with a leading ~, $HOME, XDG dir or $TMPDIR
+      # expanded: PathResolve.expand_head). After $TMPDIR the fixed part
+      # counts only inside a denied root, not as the start of one's name: an
+      # isolated run keeps its state dir in tmp, and `ls $TMPDIR/*` is no
+      # reach for it. A script body (spaces, quotes), a data heredoc or a
+      # $(…) is left to the other checks.
       def unresolved_secret?(word)
         return false if word.include?("\0") || word.match?(ShellPaths::SCRIPT)
 
-        expanded = word.sub(%r{\A~(?=/|\z)}, @home).sub(/\A\$(?:\{HOME\}|HOME\b)/, @home)
+        expanded = PathResolve.expand_head(word, home: @home, env: ENV)
         fixed = expanded[/\A[^*?\[\]{}$]*/]
         dir = @cwd || Dir.pwd
         if !expanded.include?("$") && expanded.match?(GLOB)
@@ -427,18 +480,22 @@ module Samagotchi
         end
         return false if fixed.empty?
 
-        leads_into_denied?(File.expand_path(fixed, dir))
+        prefix = File.expand_path(fixed, dir)
+        word.match?(TMPDIR_WORD) ? inside_denied?(prefix) : leads_into_denied?(prefix)
       end
 
+      # Whether a path's text is a denied root or inside one.
+      def inside_denied?(path) = @paths.denied_roots.any? { |root| PathResolve.under?(path, root) }
+
       # Whether a path's text is the start of a denied root's (its parent,
       # or part of its name: ~/.ss) or inside one.
       def leads_into_denied?(prefix)
-        @paths.denied_roots.any? { |root| root.start_with?(prefix) || ShellPaths.within?(prefix, root) }
+        @paths.denied_roots.any? { |root| root.start_with?(prefix) || PathResolve.under?(prefix, root) }
       end
 
       # Whether +path+ is a denied root's folder or one above it.
       def above_denied?(path)
-        ProtectedPaths.reals(path).any? { |real| @paths.denied_roots.any? { |root| ShellPaths.within?(root, real) } }
+        PathResolve.reals(path).any? { |real| @paths.denied_roots.any? { |root| PathResolve.under?(root, real) } }
       end
 
       def link_command?(words)
@@ -524,7 +581,7 @@ module Samagotchi
       def text_inside?(walk, text)
         return true unless text.match?(%r{\A(?:~|\.\.|/)})
 
-        expanded = text.sub(%r{\A~(?=/|\z)}, @home)
+        expanded = expand_tilde(text)
         return false if expanded.start_with?("~")
 
         walk.dirs.all? { |dir| (dir || expanded.start_with?("/")) && writable?(File.expand_path(expanded, dir || "/")) }
@@ -549,12 +606,15 @@ module Samagotchi
           if SHELLS.include?(program) || program == "eval"
             !nested(script).outside_writes?
           else
-            script.scan(SCRIPT_PATH).all? { |path| writable?(File.expand_path(path.sub(%r{\A~(?=/|\z)}, @home), @cwd || Dir.pwd)) }
+            script.scan(SCRIPT_PATH).all? { |path| writable?(File.expand_path(expand_tilde(path), @cwd || Dir.pwd)) }
           end
         end
       end
 
       def writable?(path) = PairCommand.writable?(path, root: @root, cwd: @cwd)
+
+      # +text+ with a leading ~ (alone or before a /) as the home folder.
+      def expand_tilde(text) = text.sub(%r{\A~(?=/|\z)}, @home)
     end
   end
 end

data/lib/samagotchi/guardrails/parent_approvals.rb

@@ -6,6 +6,8 @@ require_relative "../memory_paths"
 require_relative "../hooks/loader"
 require_relative "approval"
 require_relative "verdict"
+require_relative "chi_dirs"
+require_relative "path_resolve"
 require_relative "protected_paths"
 
 module Samagotchi
@@ -80,23 +82,18 @@ module Samagotchi
 
         dirs = chi_dirs
         paths = Array(fetch(facts, :paths)).map(&:to_s).reject(&:empty?)
-        reals = paths.flat_map { |path| ProtectedPaths.reals(path) }
-        return true if reals.any? { |real| dirs.any? { |dir| ProtectedPaths.within?(real, dir) } }
+        reals = paths.flat_map { |path| PathResolve.reals(path) }
+        return true if reals.any? { |real| dirs.any? { |dir| PathResolve.within?(real, dir) } }
 
         command = fetch(facts, :command).to_s
         return false if command.empty?
 
-        command.match?(CHI_TEXT) || dirs.any? { |dir| command.include?(dir) || command.include?(ProtectedPaths.real(dir)) }
+        command.match?(CHI_TEXT) || dirs.any? { |dir| command.include?(dir) || command.include?(PathResolve.real(dir)) }
       end
 
-      # chi's config dir, the hooks dir, the approval store's dir and the
-      # installed bundles' dir.
-      def chi_dirs
-        hooks = begin Hooks::Loader.hooks_dir rescue nil end
-        bundles = begin MemoryPaths.bundles_dir rescue nil end
-        [ConfigFile.config_dir, hooks, File.join(Paths.state_dir, "guardrails"), bundles, File.join(Paths.state_dir, "context")]
-          .compact.map { |dir| dir.to_s.chomp("/") }.reject(&:empty?).uniq
-      end
+      # chi's config dir, the hooks dir, the approval store's dir, the
+      # installed bundles' dir and attached context (ChiDirs.protected).
+      def chi_dirs = ChiDirs.protected
 
       # An approval: its kind says so, or it carries approval facts.
       def approval?(pending)

data/lib/samagotchi/guardrails/path_resolve.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+
+module Samagotchi
+  module Guardrails
+    # The guardrails' path primitives: how a path is expanded, resolved and
+    # compared, shared by every surface that judges one (ProtectedPaths,
+    # Outside, ShellPaths, RmTargets, ReviewPaths, PairCommand, Targets,
+    # ParentApprovals, System 1's SelfProtect). Each surface keeps its own
+    # predicate; this only says where a path lands and whether it is in a
+    # dir. docs/internals/tool-guardrails.md maps which surface uses which.
+    module PathResolve
+      # How many symlinks .real follows on a path that doesn't exist
+      # (about the kernel's own ELOOP limit).
+      MAX_LINKS = 40
+
+      # $HOME, ${HOME} and the XDG dirs at a word's start (.expand_word).
+      EXPANSION = /\A\$(?:\{(HOME|XDG_[A-Z_]+|TMPDIR)\}|(HOME|XDG_[A-Z_]+|TMPDIR)\b)/
+      # Where XDG dirs default when unset.
+      XDG_DEFAULTS = { "XDG_CONFIG_HOME" => ".config", "XDG_STATE_HOME" => ".local/state",
+                       "XDG_DATA_HOME" => ".local/share", "XDG_CACHE_HOME" => ".cache" }.freeze
+
+      # The tmp dirs besides Dir.tmpdir (.tmp_roots).
+      TMP_DIRS = %w[/tmp /var/tmp].freeze
+
+      # A dir's disk answer (.folds_case?), asked once per dir.
+      FOLDS = {}
+      FOLDS_MUTEX = Mutex.new
+
+      module_function
+
+      # +path+ as an absolute path the way the kernel opens it: ~ expanded,
+      # relative to +base+, and each `..` taken from where the dir before it
+      # really is (a `..` after a symlinked dir climbs out of its target,
+      # not back to the link's parent as File.expand_path has it). It
+      # differs from File.expand_path only for such a climb; the parts
+      # after the last `..` are kept as given (symlinks not resolved).
+      # A shell's cd may land at either (ShellPaths::Walk keeps both); a file
+      # argument and a tool's path go through this.
+      # @param path [String]
+      # @param base [String, nil] for a relative path (Dir.pwd when nil)
+      def expand(path, base = nil)
+        path = path.to_s
+        head, sep, tail = path.partition("/")
+        path = "#{File.expand_path(head)}#{sep}#{tail}" if head.start_with?("~")
+        path = File.join(File.expand_path(base || Dir.pwd), path) unless path.start_with?("/")
+        parts = []
+        path.split("/").each do |part|
+          next if part.empty? || part == "."
+
+          part == ".." ? parts = climb(parts) : parts << part
+        end
+        "/#{parts.join("/")}"
+      end
+
+      # The parts of +parts+'s parent dir: the lexical one unless the dir
+      # is (or goes through) a symlink whose target's parent is elsewhere.
+      def climb(parts)
+        lexical = parts[0...-1]
+        dir = "/#{parts.join("/")}"
+        return lexical unless parts.any? && File.directory?(dir)
+
+        physical = File.dirname(File.realpath(dir))
+        return lexical if File.realpath("/#{lexical.join("/")}") == physical
+
+        physical.split("/").reject(&:empty?)
+      rescue SystemCallError
+        lexical
+      end
+
+      # +path+ (.expand) with symlinks resolved on its longest existing
+      # parent: where the kernel lands for it. A part that is a dangling
+      # symlink is followed to its target (a write there creates the
+      # target), up to MAX_LINKS times; the missing tail is kept as given.
+      def real(path)
+        path = expand(path)
+        MAX_LINKS.times do
+          resolved = existing_prefix_real(path)
+          return resolved unless resolved.is_a?(Array)
+
+          path = resolved.first
+        end
+        path
+      rescue SystemCallError
+        path
+      end
+
+      # The old, lexical answer: File.expand_path (lexical `..`), then
+      # realpath of the longest existing prefix, stopping at a dangling
+      # symlink. .reals keeps it beside .real.
+      def lexical_real(path)
+        path = File.expand_path(path)
+        rest = []
+        current = path
+        until File.exist?(current) || current == File.dirname(current)
+          rest.unshift(File.basename(current))
+          current = File.dirname(current)
+        end
+        File.join(File.realpath(current), *rest)
+      rescue SystemCallError
+        path
+      end
+
+      # Every place +path+ may be judged as: .lexical_real (what these
+      # checks always looked at) and .real (where the kernel lands), one
+      # entry when they agree. A check that holds for any of them (a
+      # protected dir, a secret) or refuses unless all of them are inside
+      # (the project, tmp) refuses at least what it did with the lexical
+      # answer alone.
+      # @return [Array<String>]
+      def reals(path) = [lexical_real(path), real(path)].uniq
+
+      # realpath of +path+'s longest existing prefix with the rest
+      # appended (a String), or [the path with the first dangling symlink
+      # on the way replaced by its target] to resolve again.
+      def existing_prefix_real(path)
+        rest = []
+        current = path
+        until File.exist?(current) || current == File.dirname(current)
+          if File.symlink?(current)
+            target = expand(File.readlink(current), File.dirname(current))
+            return [expand(File.join(target, *rest))]
+          end
+          rest.unshift(File.basename(current))
+          current = File.dirname(current)
+        end
+        File.join(File.realpath(current), *rest)
+      end
+      private_class_method :climb, :existing_prefix_real
+
+      # Whether +path+ (resolved) is +root+ or in it, +root+ resolved
+      # either way (.reals).
+      def within?(path, root)
+        return false if root.nil? || root.to_s.empty?
+
+        reals(root.to_s.chomp("/")).any? { |dir| under?(path, dir) }
+      end
+
+      # Whether +path+ is +dir+ or in it (both absolute, resolved): by their
+      # text, or on a disk that folds case (macOS) by their text cased alike.
+      # realpath gives an existing part its on-disk case, but a missing
+      # tail keeps the case it was typed in (<state>/CONTEXT/x before
+      # <state>/context exists), and the kernel will create it in the
+      # folder that later answers to either. With +fold+ false, by their
+      # text alone.
+      def under?(path, dir, fold: true)
+        return true if path == dir || path.start_with?(File.join(dir, ""))
+        return false unless fold
+
+        low = path.downcase
+        low_dir = dir.downcase
+        (low == low_dir || low.start_with?(File.join(low_dir, ""))) && folds_case?(dir)
+      end
+
+      # Whether +path+ is in +dir+, not +dir+ itself (.under?'s terms).
+      def strictly_under?(path, dir, fold: true)
+        return true if path.start_with?(File.join(dir, ""))
+        return false unless fold
+
+        path.downcase.start_with?(File.join(dir.downcase, "")) && folds_case?(dir)
+      end
+
+      # The tmp dirs that exist (Dir.tmpdir, /tmp, /var/tmp), resolved; read
+      # each time (specs and a call's env: change TMPDIR). With +session+
+      # (a resolved session root) only those it isn't in, by their text
+      # (exact case): a session rooted in tmp gets no tmp dir of its own.
+      # @param roots [Array<String>, nil] the tmp dirs to filter (these by
+      #   default)
+      def tmp_roots(session: nil, roots: nil)
+        roots ||= [Dir.tmpdir, *TMP_DIRS].filter_map do |dir|
+          File.realpath(dir) if File.directory?(dir)
+        rescue SystemCallError
+          nil
+        end.uniq
+        session ? roots.reject { |tmp| under?(session, tmp, fold: false) } : roots
+      end
+
+      # A shell word with a leading ~, $HOME/${HOME}, an XDG dir or $TMPDIR
+      # expanded (+env+'s value, an unset XDG dir its default under +home+);
+      # nil when a $ or ~ is left. ShellPaths::Walk (cd and file words) and
+      # ShellGitDirs (git -C and the like) expand this way.
+      def expand_word(word, home:, env:)
+        word = expand_head(word, home: home, env: env)
+        return nil if word.include?("$") || word.start_with?("~")
+
+        word
+      end
+
+      # +word+ with its leading ~, $HOME/${HOME}, XDG dir or $TMPDIR
+      # expanded as .expand_word does, the rest kept as it is ($ and globs
+      # included); an unset variable without a default leaves a "$".
+      def expand_head(word, home:, env:)
+        word = word.sub(%r{\A~(?=/|\z)}) { home }
+        word.sub(EXPANSION) { variable(Regexp.last_match(1) || Regexp.last_match(2), home, env) || "$" }
+      end
+
+      def variable(name, home, env)
+        return home if name == "HOME"
+
+        set = env[name].to_s
+        return set unless set.empty?
+
+        XDG_DEFAULTS[name] && File.join(home, XDG_DEFAULTS[name])
+      end
+      private_class_method :variable
+
+      # Whether the disk +path+'s deepest existing dir is on folds case: that
+      # dir (or the first one above it with a letter in its name) answers to
+      # its name with the case swapped. Asked once per dir. A relative or
+      # blank path has no disk to ask: false.
+      def folds_case?(path)
+        return false unless path.to_s.start_with?("/")
+
+        probe = path
+        probe = File.dirname(probe) until probe == "/" || File.directory?(probe)
+        probe = File.dirname(probe) until probe == "/" || File.basename(probe).swapcase != File.basename(probe)
+        return false if probe == "/"
+
+        FOLDS_MUTEX.synchronize do
+          FOLDS.fetch(probe) do
+            other = File.join(File.dirname(probe), File.basename(probe).swapcase)
+            FOLDS[probe] = File.exist?(other) && File.identical?(probe, other)
+          end
+        end
+      rescue SystemCallError
+        false
+      end
+    end
+  end
+end