iostreams 2.0.0 → 2.1.0

data/lib/io_streams/builder.rb

@@ -105,6 +105,18 @@ module IOStreams
       @format = format
     end
 
+    # Returns [String] the quote character within which field delimiters and newlines may be
+    # embedded for the current tabular format, or [nil] when the format has no such quoting,
+    # or when the format cannot be determined.
+    #
+    # Used by the line reader to avoid treating a newline as a line ending when it is embedded
+    # within a quoted field (e.g. CSV). Delegates to the format's parser, so the per-format
+    # knowledge lives with the parser. Driven entirely by `format`, so an explicitly set format
+    # (e.g. `.format(:psv)`) overrides any extension auto-detected from the `file_name`.
+    def quote_character
+      format && IOStreams::Tabular.parser_class(format).quote_character
+    end
+
     private
 
     def build_pipeline
@@ -146,14 +158,62 @@ module IOStreams
         block.call(io_stream)
       elsif pipeline.size == 1
         stream, opts = pipeline.first
-        class_for_stream(type, stream).open(io_stream, **opts, &block)
+        open_stream(type, stream, io_stream, opts, &block)
       else
         # Daisy chain multiple streams together
         last = pipeline.keys.inject(block) do |inner, stream_sym|
-          ->(io) { class_for_stream(type, stream_sym).open(io, **pipeline[stream_sym], &inner) }
+          ->(io) { open_stream(type, stream_sym, io, pipeline[stream_sym], &inner) }
         end
         last.call(io_stream)
       end
     end
+
+    def open_stream(type, stream, io_stream, opts, &)
+      klass = class_for_stream(type, stream)
+      validate_options(type, stream, klass, opts)
+      klass.open(io_stream, **opts, &)
+    end
+
+    # Options are strict: an option the stream does not accept raises instead of being ignored.
+    # One option hash is shared by the reader and the writer for a stream, so when the option
+    # is only valid in the other direction the message says so.
+    #
+    # Streams registered via `IOStreams.register_extension` need not inherit from `IOStreams::Reader`
+    # or `IOStreams::Writer`, so a class that does not declare `option_names` is not validated here.
+    def validate_options(type, stream, klass, opts)
+      accepted = option_names(klass)
+      return if accepted.nil?
+
+      unknown = opts.keys - accepted
+      return if unknown.empty?
+
+      other_type  = type == :reader ? :writer : :reader
+      other_names = option_names(IOStreams.extensions[stream].send("#{other_type}_class")) || []
+      other_only  = unknown & other_names
+      invalid     = unknown - other_names
+      direction   = type == :reader ? "reading" : "writing"
+
+      messages = []
+      if other_only.any?
+        messages << "#{list(other_only)} only #{other_only.size == 1 ? 'applies' : 'apply'} when " \
+                    "#{type == :reader ? 'writing' : 'reading'} a #{stream.inspect} stream and cannot be used when " \
+                    "#{direction}. Configure a separate path or stream without #{other_only.size == 1 ? 'it' : 'them'} " \
+                    "for #{direction}."
+      end
+      if invalid.any?
+        valid = accepted.empty? ? "none" : list(accepted)
+        messages << "Unknown #{invalid.size == 1 ? 'option' : 'options'} #{list(invalid)} when #{direction} " \
+                    "a #{stream.inspect} stream. Valid options: #{valid}."
+      end
+      raise(ArgumentError, messages.join(" "))
+    end
+
+    def option_names(klass)
+      klass.option_names if klass.respond_to?(:option_names)
+    end
+
+    def list(names)
+      names.map(&:inspect).join(", ")
+    end
   end
 end

data/lib/io_streams/bzip2/reader.rb

@@ -1,12 +1,35 @@
 module IOStreams
   module Bzip2
     class Reader < IOStreams::Reader
+      OPTION_NAMES = %i[autoclose first_only small].freeze
+
+      # Not declared until v3.0, so that an unknown option logs a warning instead of raising `ArgumentError`.
+      def self.option_names
+        nil
+      end
+
       # Read from a Bzip2 stream, decompressing the contents as it is read
-      def self.stream(input_stream, **args)
+      #
+      # Any other option is ignored and logs a warning. It will raise `ArgumentError` in v3.0.
+      #
+      # Parameters are passed through to `Bzip2::FFI::Reader`:
+      #   autoclose: [true|false]
+      #     Close the input stream when the reader is closed.
+      #     Default: false
+      #
+      #   first_only: [true|false]
+      #     Only decompress the first of any consecutive bzip2 structures in the input.
+      #     Default: false
+      #
+      #   small: [true|false]
+      #     Use an alternative decompression algorithm that uses less memory but is slower.
+      #     Default: false
+      def self.stream(input_stream, autoclose: false, first_only: false, small: false, **unknown)
+        Utils.warn_unknown_options(unknown, :bz2, "reading", OPTION_NAMES)
         Utils.load_soft_dependency("bzip2-ffi", "Bzip2", "bzip2/ffi") unless defined?(::Bzip2::FFI)
 
         begin
-          io = ::Bzip2::FFI::Reader.new(input_stream, args)
+          io = ::Bzip2::FFI::Reader.new(input_stream, autoclose: autoclose, first_only: first_only, small: small)
           yield io
         ensure
           io&.close

data/lib/io_streams/bzip2/writer.rb

@@ -1,12 +1,36 @@
 module IOStreams
   module Bzip2
     class Writer < IOStreams::Writer
+      OPTION_NAMES = %i[autoclose block_size work_factor].freeze
+
+      # Not declared until v3.0, so that an unknown option logs a warning instead of raising `ArgumentError`.
+      def self.option_names
+        nil
+      end
+
       # Write to a stream, compressing with Bzip2
-      def self.stream(input_stream, **args)
+      #
+      # Any other option is ignored and logs a warning. It will raise `ArgumentError` in v3.0.
+      #
+      # Parameters are passed through to `Bzip2::FFI::Writer`:
+      #   autoclose: [true|false]
+      #     Close the output stream when the writer is closed.
+      #     Default: false
+      #
+      #   block_size: [Integer]
+      #     Compression block size, from 1 (100k) to 9 (900k).
+      #     Default: 9
+      #
+      #   work_factor: [Integer]
+      #     How much effort to spend on highly repetitive input before falling back
+      #     to a slower algorithm, from 0 to 250. 0 uses the libbz2 default.
+      #     Default: 0
+      def self.stream(input_stream, autoclose: false, block_size: nil, work_factor: nil, **unknown)
+        Utils.warn_unknown_options(unknown, :bz2, "writing", OPTION_NAMES)
         Utils.load_soft_dependency("bzip2-ffi", "Bzip2", "bzip2/ffi") unless defined?(::Bzip2::FFI)
 
         begin
-          io = ::Bzip2::FFI::Writer.new(input_stream, args)
+          io = ::Bzip2::FFI::Writer.new(input_stream, autoclose: autoclose, block_size: block_size, work_factor: work_factor)
           yield io
         ensure
           io&.close

data/lib/io_streams/encode/reader.rb

@@ -1,6 +1,10 @@
 module IOStreams
   module Encode
     class Reader < IOStreams::Reader
+      def self.option_names
+        %i[encoding cleaner replace]
+      end
+
       attr_reader :encoding, :cleaner
 
       NOT_PRINTABLE = /[^[:print:]|\r\n]/

data/lib/io_streams/encode/writer.rb

@@ -1,6 +1,10 @@
 module IOStreams
   module Encode
     class Writer < IOStreams::Writer
+      def self.option_names
+        %i[encoding cleaner replace]
+      end
+
       attr_reader :encoding, :cleaner
 
       # Write a line at a time to a file or stream

data/lib/io_streams/errors.rb

@@ -18,6 +18,10 @@ module IOStreams
     class CommunicationsFailure < Error
     end
 
+    # When a path is not within any of the allowed paths, see `IOStreams.add_allowed_path`.
+    class AccessDenied < Error
+    end
+
     # When the specified delimiter is not found in the supplied stream / file
     class DelimiterNotFound < Error
     end

data/lib/io_streams/gzip/reader.rb

@@ -1,6 +1,10 @@
 module IOStreams
   module Gzip
     class Reader < IOStreams::Reader
+      def self.option_names
+        []
+      end
+
       # Read from a gzip stream, decompressing the contents as it is read
       def self.stream(input_stream)
         io = ::Zlib::GzipReader.new(input_stream)

data/lib/io_streams/gzip/writer.rb

@@ -1,9 +1,18 @@
 module IOStreams
   module Gzip
     class Writer < IOStreams::Writer
+      def self.option_names
+        %i[level]
+      end
+
       # Write to a stream, compressing with GZip
-      def self.stream(input_stream, &block)
-        io = ::Zlib::GzipWriter.new(input_stream)
+      #
+      # Parameters
+      #   level: [Integer]
+      #     Compression level, from 0 (no compression) to 9 (best compression).
+      #     Default: Zlib::DEFAULT_COMPRESSION
+      def self.stream(input_stream, level: nil, &block)
+        io = ::Zlib::GzipWriter.new(input_stream, level)
         block.call(io)
       ensure
         io&.close

data/lib/io_streams/io_streams.rb

@@ -119,8 +119,12 @@ module IOStreams
   #
   # Example:
   #   IOStreams.temp_file("export", ".csv") { |path| path.write("Hello World") }
+  #
+  # Note: The temp file is accessible even when it is not within the allowed paths, see `IOStreams.add_allowed_path`.
   def self.temp_file(basename, extension = "")
-    Utils.temp_file_name(basename, extension) { |file_name| yield(Paths::File.new(file_name).stream(:none)) }
+    Utils.temp_file_name(basename, extension) do |file_name|
+      yield(Paths::File.new(file_name).send(:permit!).stream(:none))
+    end
   end
 
   # Returns [IOStreams::Paths::File] current or named users home path
@@ -241,6 +245,77 @@ module IOStreams
     @root_paths.dup
   end
 
+  # Restrict IOStreams to only access paths within the supplied path.
+  #
+  # Once any allowed path has been added, reading, writing, listing, deleting or otherwise accessing
+  # a path that is not within one of the allowed paths raises `IOStreams::Errors::AccessDenied`.
+  # This prevents an untrusted file name, for example one supplied by a user, from accessing anything
+  # else that the process can access.
+  #
+  # Parameters: Same as `IOStreams.path`
+  #
+  # Returns [String] the normalized path that was added, against which paths are compared.
+  #
+  # Example:
+  #    IOStreams.add_allowed_path("/var/data/uploads")
+  #    IOStreams.add_allowed_path("s3://my-bucket/exports")
+  #
+  #    IOStreams.path("/var/data/uploads/file.csv").read
+  #    IOStreams.path("/etc/passwd").read
+  #    # => IOStreams::Errors::AccessDenied
+  #
+  # Notes:
+  # * By default no allowed paths are added, and every path is accessible.
+  # * Add allowed paths in an initializer at startup, where they cannot be changed by untrusted input.
+  # * Paths are normalized before they are compared, so `..` cannot be used to leave an allowed path:
+  #   * Local file names are resolved to their real path, following symbolic links.
+  #     A relative path is resolved against the current working directory when it is added.
+  #   * For S3 the bucket must match, and keys containing `.` or `..` segments are denied.
+  #   * For SFTP and HTTP the host and port must match, and `.` and `..` segments are resolved.
+  # * `#each_child` skips children that are not within the allowed paths, for example a symbolic link
+  #   to a file elsewhere.
+  # * Temp files created by `IOStreams.temp_file` are always accessible.
+  # * Paths from a scheme registered with `IOStreams.register_scheme` are denied, unless its path class
+  #   implements the private method `#allowed_location`.
+  # * A local file could be replaced with a symbolic link after it is checked but before it is opened.
+  #   Allowed paths do not prevent this, so do not allow paths where untrusted users can create files.
+  def self.add_allowed_path(*elements, **args)
+    location = allowed_location(path(*elements, **args))
+    @allowed_paths_mutex.synchronize { @allowed_paths = (@allowed_paths + [location]).uniq.freeze }
+    location
+  end
+
+  # Removes a path previously added with `IOStreams.add_allowed_path`.
+  #
+  # Returns [String] the normalized path that was removed.
+  def self.delete_allowed_path(*elements, **args)
+    location = allowed_location(path(*elements, **args))
+    @allowed_paths_mutex.synchronize { @allowed_paths = (@allowed_paths - [location]).freeze }
+    location
+  end
+
+  # Returns [Array<String>] the normalized allowed paths, see `IOStreams.add_allowed_path`.
+  def self.allowed_paths
+    @allowed_paths
+  end
+
+  # Returns [true|false] whether the supplied path can be accessed, see `IOStreams.add_allowed_path`.
+  #
+  # Always true when no allowed paths have been added.
+  #
+  # Parameters: Same as `IOStreams.path`
+  def self.allowed_path?(*elements, **args)
+    path(*elements, **args).send(:allowed?)
+  end
+
+  def self.allowed_location(path)
+    path.send(:allowed_location)
+  rescue Errors::AccessDenied => e
+    raise(ArgumentError, e.message)
+  end
+
+  private_class_method :allowed_location
+
   # Set the temporary path to use when creating local temp files.
   def self.temp_dir=(temp_dir)
     temp_dir = File.expand_path(temp_dir)
@@ -259,6 +334,37 @@ module IOStreams
 
   @temp_dir = nil
 
+  # Apply `allowed_columns`, `required_columns` and `skip_unknown` to every input when reading records.
+  #
+  # When false, they only apply to a header row read from the file, and only when `cleanse_header` is true.
+  # They are ignored for JSON and `:hash` input, when `columns:` is supplied, and with `cleanse_header: false`,
+  # and a warning is logged when applying them would change the result.
+  #
+  # When true, they also apply to the supplied `columns:`, to a header row read with `cleanse_header: false`,
+  # and to the keys of each JSON or `:hash` record. JSON keys are cleansed like a header row, unless
+  # `cleanse_header` is false, unknown keys are skipped or raise `IOStreams::Errors::InvalidHeader`,
+  # and a record missing a required column raises `IOStreams::Errors::InvalidHeader`.
+  #
+  # Since the format is usually inferred from the file name, set this to true when the allowed columns
+  # restrict what an uploaded file can set, so that renaming the file to `.json` cannot bypass them.
+  #
+  # Default: false. It will default to true in v3.0.
+  #
+  # Example:
+  #   IOStreams.enforce_column_restrictions = true
+  def self.enforce_column_restrictions=(enforce)
+    raise(ArgumentError, "enforce_column_restrictions must be true or false") unless [true, false].include?(enforce)
+
+    @enforce_column_restrictions = enforce
+  end
+
+  # Returns [true|false] whether column restrictions apply to every input, see `IOStreams.enforce_column_restrictions=`.
+  def self.enforce_column_restrictions?
+    @enforce_column_restrictions
+  end
+
+  @enforce_column_restrictions = false
+
   # Returns [Logger] the logger used by IOStreams for debug logging.
   #
   # When SemanticLogger is loaded a SemanticLogger instance is used by default,
@@ -327,6 +433,10 @@ module IOStreams
   # Hold root paths
   @root_paths = {}
 
+  # Hold allowed paths. Replaced rather than modified, so that it can be read without a lock.
+  @allowed_paths       = [].freeze
+  @allowed_paths_mutex = Mutex.new
+
   # A registry to hold formats for processing files during upload or download
   @extensions = {}
   @schemes    = {}

data/lib/io_streams/line/reader.rb

@@ -43,7 +43,8 @@ module IOStreams
       #     For CSV files set `embedded_within: '"'`
       #
       # Note:
-      # * When using a line reader and the file_name ends with ".csv" then embedded_within is automatically set to `"`
+      # * When reached via `IOStreams::Stream`, `embedded_within` defaults to the quote character of the
+      #   resolved tabular format (e.g. `"` for CSV). See `IOStreams::Builder#quote_character`.
       def initialize(input_stream, delimiter: nil, buffer_size: 65_536, embedded_within: nil)
         super(input_stream)
 
@@ -93,7 +94,9 @@ module IOStreams
         line = _readline
         if line && @embedded_within
           initial_line_number = @line_number
-          while line.count(@embedded_within).odd?
+          # Count the delimiters incrementally, since recounting the whole line each time is quadratic.
+          embedded_count      = line.count(@embedded_within)
+          while embedded_count.odd?
             if eof? || line.length > @buffer_size * 10
               raise(Errors::MalformedDataError.new(
                       "Unbalanced delimited field, delimiter: #{@embedded_within}",
@@ -101,6 +104,7 @@ module IOStreams
                     ))
             end
             line << @delimiter
+            embedded_count += @delimiter.count(@embedded_within)
             next_line = _readline
             if next_line.nil?
               raise(Errors::MalformedDataError.new(
@@ -109,6 +113,7 @@ module IOStreams
                     ))
             end
             line << next_line
+            embedded_count += next_line.count(@embedded_within)
           end
         end
         line

data/lib/io_streams/path.rb

@@ -1,5 +1,9 @@
 module IOStreams
   class Path < IOStreams::Stream
+    # Stream option names whose values must not be displayed, such as `passphrase` or `signer_passphrase`.
+    SENSITIVE_OPTION = /pass(phrase|word)|secret/i
+    private_constant :SENSITIVE_OPTION
+
     attr_accessor :path
 
     def initialize(path)
@@ -21,7 +25,7 @@ module IOStreams
 
       new_path         = dup
       new_path.builder = nil
-      new_path.path    = relative.start_with?(path) ? relative : ::File.join(path, relative)
+      new_path.path    = contains?(relative) ? relative : ::File.join(path, relative)
       new_path
     end
 
@@ -57,6 +61,24 @@ module IOStreams
       path
     end
 
+    # See Stream#reader.
+    #
+    # Raises [IOStreams::Errors::AccessDenied] when this path is not within any of the allowed paths,
+    # see `IOStreams.add_allowed_path`.
+    def reader(...)
+      authorize!
+      super
+    end
+
+    # See Stream#writer.
+    #
+    # Raises [IOStreams::Errors::AccessDenied] when this path is not within any of the allowed paths,
+    # see `IOStreams.add_allowed_path`.
+    def writer(...)
+      authorize!
+      super
+    end
+
     # Removes the last element of the path, the file name, before creating the entire path.
     # Returns self
     def mkpath
@@ -82,7 +104,7 @@ module IOStreams
     end
 
     # Cleanup an incomplete write to the target "file" if the copy fails.
-    # rubocop:disable Lint/SuppressedException
+    # rubocop:disable-next Lint/SuppressedException
     def copy_from(source, **args)
       super
     rescue StandardError => e
@@ -92,7 +114,6 @@ module IOStreams
       end
       raise(e)
     end
-    # rubocop:enable Lint/SuppressedException
 
     # Moves the file by copying it to the new path and then deleting the current path.
     # Returns [IOStreams::Path] the target path.
@@ -190,15 +211,103 @@ module IOStreams
 
     def inspect
       str = "#<#{self.class.name}:#{path}"
-      str << " @builder=#{builder.streams.inspect}" if builder.streams
-      str << " @options=#{builder.options.inspect}" if builder.options
-      str << " pipeline=#{pipeline.inspect}>"
+      str << " @builder=#{redact(builder.streams).inspect}" if builder.streams
+      str << " @options=#{redact(builder.options).inspect}" if builder.options
+      str << " pipeline=#{redact(pipeline).inspect}>"
+    end
+
+    protected
+
+    # Raises [IOStreams::Errors::AccessDenied] when allowed paths have been added, see `IOStreams.add_allowed_path`,
+    # and this path is not within any of them.
+    def authorize!
+      return if IOStreams.allowed_paths.empty? || (@permitted_path && @permitted_path == path)
+
+      authorize_location!(allowed_location)
+    end
+
+    # Returns [true|false] whether this path is within the allowed paths, see `#authorize!`.
+    def allowed?
+      authorize!
+      true
+    rescue Errors::AccessDenied
+      false
     end
 
     private
 
+    # Returns [String] the normalized location of this path, which is compared against the allowed paths.
+    #
+    # Each path class that can be used with allowed paths overrides this method. Without it every path
+    # of that class is denied once allowed paths have been added.
+    #
+    # Raises [IOStreams::Errors::AccessDenied] when the location cannot be determined.
+    def allowed_location
+      raise(Errors::AccessDenied, "Access denied: #{self.class.name} does not support allowed paths")
+    end
+
+    # Raises [IOStreams::Errors::AccessDenied] when the supplied location, see `#allowed_location`,
+    # is not within any of the allowed paths.
+    def authorize_location!(location)
+      return if IOStreams.allowed_paths.any? { |allowed_path| within?(location, allowed_path) }
+
+      raise(Errors::AccessDenied, "Access denied to #{location}: it is not within any of the allowed paths")
+    end
+
+    # Returns [String] the supplied path with `.`, `..` and repeated `/` resolved, the way a remote server
+    # resolves them, without accessing it. The path always starts with `/`, and `..` cannot go above it.
+    def normalize_path(name)
+      segments = []
+      name.split("/").each do |segment|
+        case segment
+        when "", "."
+          next
+        when ".."
+          segments.pop
+        else
+          segments << segment
+        end
+      end
+      "/#{segments.join('/')}"
+    end
+
+    # Returns [true|false] whether a child found by `#each_child` is within the allowed paths, logging it when it is not.
+    def allowed_child?(child)
+      return true if child.allowed?
+
+      IOStreams.logger&.warn("Skipping #{child} since it is not within any of the allowed paths")
+      false
+    end
+
+    # Allows this exact path regardless of the allowed paths, for paths created by IOStreams itself such as temp files.
+    # Returns self
+    def permit!
+      @permitted_path = path
+      self
+    end
+
+    # Returns [Hash<Symbol:Hash>] the streams with the values of sensitive options replaced.
+    def redact(streams)
+      streams.transform_values do |options|
+        next options unless options.is_a?(Hash)
+
+        options.to_h { |name, value| [name, name.to_s.match?(SENSITIVE_OPTION) ? "[FILTERED]" : value] }
+      end
+    end
+
     def builder
       @builder ||= IOStreams::Builder.new(path)
     end
+
+    # Returns [true|false] whether the supplied path is this path, or is within this path.
+    # For example "a/b" contains "a/b/c.csv", but not "a/bc.csv".
+    def contains?(other)
+      path.empty? || within?(other, path)
+    end
+
+    # Returns [true|false] whether the path `child` is `parent`, or is within `parent`.
+    def within?(child, parent)
+      child == parent || child.start_with?(parent.end_with?("/") ? parent : "#{parent}/")
+    end
   end
 end

data/lib/io_streams/paths/file.rb

@@ -94,6 +94,8 @@ module IOStreams
                          case_sensitive: case_sensitive, directories: directories, hidden: hidden)
         end
 
+        authorize!
+
         flags = 0
         flags |= ::File::FNM_CASEFOLD unless case_sensitive
         flags |= ::File::FNM_DOTMATCH if hidden
@@ -116,7 +118,8 @@ module IOStreams
         results.each do |full_path|
           next if !directories && ::File.directory?(full_path)
 
-          yield(self.class.new(full_path))
+          child = self.class.new(full_path)
+          yield(child) if allowed_child?(child)
         end
       end
 
@@ -128,6 +131,8 @@ module IOStreams
         target = IOStreams.new(target_path)
         return super(target) unless target.is_a?(self.class)
 
+        authorize!
+        target.authorize!
         target.mkpath
         # In case the file is being moved across partitions
         FileUtils.move(path, target.to_s)
@@ -135,25 +140,30 @@ module IOStreams
       end
 
       def mkpath
+        authorize!
         dir = ::File.dirname(path)
         FileUtils.mkdir_p(dir)
         self
       end
 
       def mkdir
+        authorize!
         FileUtils.mkdir_p(path)
         self
       end
 
       def exist?
+        authorize!
         ::File.exist?(path)
       end
 
       def size
+        authorize!
         ::File.size(path)
       end
 
       def delete
+        authorize!
         return self unless exist?
 
         ::File.directory?(path) ? Dir.delete(path) : ::File.unlink(path)
@@ -161,6 +171,7 @@ module IOStreams
       end
 
       def delete_all
+        authorize!
         return self unless exist?
 
         ::File.directory?(path) ? FileUtils.remove_dir(path) : ::File.unlink(path)
@@ -169,11 +180,46 @@ module IOStreams
 
       # Returns the real path by stripping `.`, `..` and expands any symlinks.
       def realpath
+        authorize!
         self.class.new(::File.realpath(path))
       end
 
       private
 
+      # Returns [String] the real path of this file, following any symbolic links, which is compared
+      # against the allowed paths.
+      #
+      # The part of the path that does not exist yet, for example a file that is about to be written,
+      # is appended to the real path of the part that does exist. It cannot contain `.` or `..`, since
+      # what they refer to depends on directories that have not been created yet.
+      def allowed_location
+        existing = ::File.absolute_path?(path) ? path : ::File.join(Dir.pwd, path)
+        missing  = []
+        until present?(existing)
+          parent = ::File.dirname(existing)
+          break if parent == existing
+
+          missing.unshift(::File.basename(existing))
+          existing = parent
+        end
+
+        if missing.intersect?([".", ".."])
+          raise(Errors::AccessDenied, "Access denied to #{path}: '.' and '..' are not allowed after a missing directory")
+        end
+
+        ::File.join(::File.realpath(existing), *missing)
+      rescue SystemCallError => e
+        raise(Errors::AccessDenied, "Access denied to #{path}: #{e.message}")
+      end
+
+      # Returns [true|false] whether the file, directory or symbolic link exists, without following the link.
+      def present?(file_name)
+        ::File.lstat(file_name)
+        true
+      rescue SystemCallError
+        false
+      end
+
       # Read from file
       def stream_reader(&block)
         ::File.open(path, "rb") { |io| builder.reader(io, &block) }