asciidoctor 1.5.6.2 → 1.5.7

data/lib/asciidoctor/path_resolver.rb

@@ -7,7 +7,7 @@ module Asciidoctor
 # The main emphasis of the class is on creating clean and secure paths. Clean
 # paths are void of duplicate parent and current directory references in the
 # path name. Secure paths are paths which are restricted from accessing
-# directories outside of a jail root, if specified.
+# directories outside of a jail path, if specified.
 #
 # Since joining two paths can result in an insecure path, this class also
 # handles the task of joining a parent (start) and child (target) path.
@@ -94,13 +94,15 @@ module Asciidoctor
 #     => '/path/to/docs/images'
 #
 #     begin
-#       resolver.system_path('images', '/etc', '/path/to/docs')
+#       resolver.system_path('images', '/etc', '/path/to/docs', recover: false)
 #     rescue SecurityError => e
 #       puts e.message
 #     end
-#     => Start path /etc is outside of jail: /path/to/docs'
+#     => start path /etc is outside of jail: /path/to/docs'
 #
 class PathResolver
+  include Logging
+
   DOT = '.'
   DOT_DOT = '..'
   DOT_SLASH = './'
@@ -118,17 +120,14 @@ class PathResolver
   # expanded to an absolute path inside the constructor.
   #
   # file_separator - the String file separator to use for path operations
-  #                  (optional, default: File::SEPARATOR)
+  #                  (optional, default: File::ALT_SEPARATOR or File::SEPARATOR)
   # working_dir    - the String working directory (optional, default: Dir.pwd)
   #
   def initialize file_separator = nil, working_dir = nil
-    @file_separator = file_separator ? file_separator : (::File::ALT_SEPARATOR || ::File::SEPARATOR)
-    if working_dir
-      @working_dir = (root? working_dir) ? working_dir : (::File.expand_path working_dir)
-    else
-      @working_dir = ::File.expand_path ::Dir.pwd
-    end
-    @_partition_path_sys, @_partition_path_web = {}, {}
+    @file_separator = file_separator || ::File::ALT_SEPARATOR || ::File::SEPARATOR
+    @working_dir = working_dir ? ((root? working_dir) ? (posixify working_dir) : (::File.expand_path working_dir)) : ::Dir.pwd
+    @_partition_path_sys = {}
+    @_partition_path_web = {}
   end
 
   # Public: Check whether the specified path is an absolute path.
@@ -196,7 +195,26 @@ class PathResolver
   #
   # returns If path descends from base, return the offset, otherwise false.
   def descends_from? path, base
-    base == path ? 0 : ((path.start_with? base + '/') ? base.length + 1 : false)
+    if base == path
+      0
+    elsif base == SLASH
+      (path.start_with? SLASH) && 1
+    else
+      (path.start_with? base + SLASH) && (base.length + 1)
+    end
+  end
+
+  # Public: Calculate the relative path to this absolute path from the specified base directory
+  #
+  # If neither path or base are absolute paths, or the path is not contained
+  # within the base directory, no work is done.
+  #
+  # path - [String] an absolute filename.
+  # base - [String] an absolute base directory.
+  #
+  # Return the [String] relative path of the specified path calculated from the base directory.
+  def relative_path path, base
+    (root? path) && (offset = descends_from? path, base) ? (path.slice offset, path.length) : path
   end
 
   # Public: Normalize path by converting any backslashes to forward slashes
@@ -205,45 +223,46 @@ class PathResolver
   #
   # returns a String path with any backslashes replaced with forward slashes
   def posixify path
-    if path.nil_or_empty?
-      ''
-    elsif path.include? BACKSLASH
-      path.tr BACKSLASH, SLASH
+    if path
+      @file_separator == BACKSLASH && (path.include? BACKSLASH) ? (path.tr BACKSLASH, SLASH) : path
     else
-      path
+      ''
     end
   end
   alias posixfy posixify
 
-  # Public: Expand the path by resolving any parent references (..)
-  # and cleaning self references (.).
-  #
-  # The result will be relative if the path is relative and
-  # absolute if the path is absolute. The file separator used
-  # in the expanded path is the one specified when the class
-  # was constructed.
+  # Public: Expand the specified path by converting the path to a posix path, resolving parent
+  # references (..), and removing self references (.).
   #
   # path - the String path to expand
   #
-  # returns a String path with any parent or self references resolved.
+  # returns a String path as a posix path with parent references resolved and self references removed.
+  # The result will be relative if the path is relative and absolute if the path is absolute.
   def expand_path path
-    path_segments, path_root, _ = partition_path path
-    join_path path_segments, path_root
+    path_segments, path_root = partition_path path
+    if path.include? DOT_DOT
+      resolved_segments = []
+      path_segments.each do |segment|
+        segment == DOT_DOT ? resolved_segments.pop : resolved_segments << segment
+      end
+      join_path resolved_segments, path_root
+    else
+      join_path path_segments, path_root
+    end
   end
 
-  # Public: Partition the path into path segments and remove any empty segments
-  # or segments that are self references (.). The path is converted to a posix
-  # path before being partitioned.
+  # Public: Partition the path into path segments and remove self references (.) and the trailing
+  # slash, if present. Prior to being partitioned, the path is converted to a posix path.
+  #
+  # Parent references are not resolved by this method since the consumer often needs to handle this
+  # resolution in a certain context (checking for the breach of a jail, for instance).
   #
   # path - the String path to partition
   # web  - a Boolean indicating whether the path should be handled
   #        as a web path (optional, default: false)
   #
-  # Returns a 3-item Array containing the Array of String path segments, the
-  # path root (e.g., '/', './', 'c:/') if the path is absolute and the posix
-  # version of the path.
-  #--
-  # QUESTION is it worth it to normalize slashes? it doubles the time elapsed
+  # Returns a 2-item Array containing the Array of String path segments and the
+  # path root (e.g., '/', './', 'c:/', or '//'), which is nil unless the path is absolute.
   def partition_path path, web = nil
     if (result = (cache = web ? @_partition_path_web : @_partition_path_sys)[path])
       return result
@@ -251,56 +270,36 @@ class PathResolver
 
     posix_path = posixify path
 
-    root = if web
+    if web
       # ex. /sample/path
       if web_root? posix_path
-        SLASH
+        root = SLASH
       # ex. ./sample/path
       elsif posix_path.start_with? DOT_SLASH
-        DOT_SLASH
-      # ex. sample/path
-      else
-        nil
+        root = DOT_SLASH
+      # else ex. sample/path
       end
-    else
-      if root? posix_path
-        # ex. //sample/path
-        if unc? posix_path
-          DOUBLE_SLASH
-        # ex. /sample/path
-        elsif posix_path.start_with? SLASH
-          SLASH
-        # ex. C:/sample/path (or file:///sample/path in browser environment)
-        else
-          posix_path.slice 0, (posix_path.index SLASH) + 1
-        end
-      # ex. ./sample/path
-      elsif posix_path.start_with? DOT_SLASH
-        DOT_SLASH
-      # ex. sample/path
+    elsif root? posix_path
+      # ex. //sample/path
+      if unc? posix_path
+        root = DOUBLE_SLASH
+      # ex. /sample/path
+      elsif posix_path.start_with? SLASH
+        root = SLASH
+      # ex. C:/sample/path (or file:///sample/path in browser environment)
       else
-        nil
+        root = posix_path.slice 0, (posix_path.index SLASH) + 1
       end
+    # ex. ./sample/path
+    elsif posix_path.start_with? DOT_SLASH
+      root = DOT_SLASH
+    # else ex. sample/path
     end
 
-    path_segments = posix_path.split SLASH
-    # shift twice for a UNC path
-    if root == DOUBLE_SLASH
-      path_segments = path_segments[2..-1]
-    # shift twice for a file:/// path and adjust root
-    # NOTE technically file:/// paths work without this adjustment
-    #elsif ::RUBY_ENGINE_OPAL && ::JAVASCRIPT_IO_MODULE == 'xmlhttprequest' && root == 'file:/'
-    #  root = 'file://'
-    #  path_segments = path_segments[2..-1]
-    # shift once for any other root
-    elsif root
-      path_segments.shift
-    end
+    path_segments = (root ? (posix_path.slice root.length, posix_path.length) : posix_path).split SLASH
     # strip out all dot entries
     path_segments.delete DOT
-    # QUESTION should we chop trailing /? (we pay a small fraction)
-    #posix_path = posix_path.chop if posix_path.end_with? SLASH
-    cache[path] = [path_segments, root, posix_path]
+    cache[path] = [path_segments, root]
   end
 
   # Public: Join the segments using the posix file separator (since Ruby knows
@@ -317,110 +316,135 @@ class PathResolver
     root ? %(#{root}#{segments * SLASH}) : segments * SLASH
   end
 
-  # Public: Resolve a system path from the target and start paths. If a jail
-  # path is specified, enforce that the resolved directory is contained within
-  # the jail path. If a jail path is not provided, the resolved path may be
-  # any location on the system. If the resolved path is absolute, use it as is.
-  # If the resolved path is relative, resolve it relative to the working_dir
-  # specified in the constructor.
+  # Public: Securely resolve a system path
+  #
+  # Resolve a system path from the target relative to the start path, jail path, or working
+  # directory (specified in the constructor), in that order. If a jail path is specified, enforce
+  # that the resolved path descends from the jail path. If a jail path is not provided, the resolved
+  # path may be any location on the system. If the resolved path is absolute, use it as is (unless
+  # it breaches the jail path). Expand all parent and self references in the resolved path.
   #
   # target - the String target path
-  # start  - the String start (i.e., parent) path (default: nil)
-  # jail   - the String jail path to confine the resolved path (default: nil)
+  # start  - the String start path from which to resolve a relative target; falls back to jail, if
+  #          specified, or the working directory specified in the constructor (default: nil)
+  # jail   - the String jail path to which to confine the resolved path, if specified; must be an
+  #          absolute path (default: nil)
   # opts   - an optional Hash of options to control processing (default: {}):
-  #          * :recover is used to control whether the processor should auto-recover
-  #              when an illegal path is encountered
+  #          * :recover is used to control whether the processor should
+  #            automatically recover when an illegal path is encountered
   #          * :target_name is used in messages to refer to the path being resolved
   #
-  # returns a String path that joins the target path with the start path with
-  # any parent references resolved and self references removed and enforces
-  # that the resolved path be contained within the jail, if provided
+  # returns a String path relative to the start path, if specified, and confined to the jail path,
+  # if specified. The path is posixified and all parent and self references in the path are expanded.
   def system_path target, start = nil, jail = nil, opts = {}
     if jail
-      unless root? jail
-        raise ::SecurityError, %(Jail is not an absolute path: #{jail})
-      end
+      raise ::SecurityError, %(Jail is not an absolute path: #{jail}) unless root? jail
+      #raise ::SecurityError, %(Jail is not a canonical path: #{jail}) if jail.include? DOT_DOT
       jail = posixify jail
     end
 
-    if target.nil_or_empty?
-      target_segments = []
+    if target
+      if root? target
+        target_path = expand_path target
+        if jail && !(descends_from? target_path, jail)
+          if opts.fetch :recover, true
+            logger.warn %(#{opts[:target_name] || 'path'} is outside of jail; recovering automatically)
+            target_segments, _ = partition_path target_path
+            jail_segments, jail_root = partition_path jail
+            return join_path jail_segments + target_segments, jail_root
+          else
+            raise ::SecurityError, %(#{opts[:target_name] || 'path'} #{target} is outside of jail: #{jail} (disallowed in safe mode))
+          end
+        end
+        return target_path
+      else
+        target_segments, _ = partition_path target
+      end
     else
-      target_segments, target_root, _ = partition_path target
+      target_segments = []
     end
 
     if target_segments.empty?
       if start.nil_or_empty?
-        return jail ? jail : @working_dir
+        return jail || @working_dir
       elsif root? start
-        unless jail
+        if jail
+          start = posixify start
+        else
           return expand_path start
         end
       else
-        return system_path start, jail, jail, opts
+        target_segments, _ = partition_path start
+        start = jail || @working_dir
       end
-    end
-
-    if target_root && target_root != DOT_SLASH
-      resolved_target = join_path target_segments, target_root
-      # if target is absolute and a sub-directory of jail, or
-      # a jail is not in place, let it slide
-      if !jail || (resolved_target.start_with? jail)
-        return resolved_target
-      end
-    end
-
-    if start.nil_or_empty?
-      start = jail ? jail : @working_dir
+    elsif start.nil_or_empty?
+      start = jail || @working_dir
     elsif root? start
-      start = posixify start
+      start = posixify start if jail
     else
-      start = system_path start, jail, jail, opts
+      #start = system_path start, jail, jail, opts
+      start = %(#{(jail || @working_dir).chomp '/'}/#{start})
     end
 
-    # both jail and start have been posixfied at this point
-    if jail == start
-      jail_segments, jail_root, _ = partition_path jail
-      start_segments = jail_segments.dup
-    elsif jail
-      unless start.start_with? jail
-        raise ::SecurityError, %(#{opts[:target_name] || 'Start path'} #{start} is outside of jail: #{jail} (disallowed in safe mode))
+    # both jail and start have been posixified at this point if jail is set
+    if jail && (recheck = !(descends_from? start, jail)) && @file_separator == BACKSLASH
+      start_segments, start_root = partition_path start
+      jail_segments, jail_root = partition_path jail
+      if start_root != jail_root
+        if opts.fetch :recover, true
+          logger.warn %(start path for #{opts[:target_name] || 'path'} is outside of jail root; recovering automatically)
+          start_segments = jail_segments
+          recheck = false
+        else
+          raise ::SecurityError, %(start path for #{opts[:target_name] || 'path'} #{start} refers to location outside jail root: #{jail} (disallowed in safe mode))
+        end
       end
-
-      start_segments, start_root, _ = partition_path start
-      jail_segments, jail_root, _ = partition_path jail
-
-      # Already checked for this condition
-      #if start_root != jail_root
-      #  raise ::SecurityError, %(Jail root #{jail_root} does not match root of #{opts[:target_name] || 'start path'}: #{start_root})
-      #end
     else
-      start_segments, start_root, _ = partition_path start
-      jail_root = start_root
+      start_segments, jail_root = partition_path start
     end
 
-    resolved_segments = start_segments.dup
-    warned = false
-    target_segments.each do |segment|
-      if segment == DOT_DOT
-        if jail
-          if resolved_segments.size > jail_segments.size
-            resolved_segments.pop
-          elsif !(recover ||= (opts.fetch :recover, true))
-            raise ::SecurityError, %(#{opts[:target_name] || 'path'} #{target} refers to location outside jail: #{jail} (disallowed in safe mode))
-          elsif !warned
-            warn %(asciidoctor: WARNING: #{opts[:target_name] || 'path'} has illegal reference to ancestor of jail, auto-recovering)
-            warned = true
+    if (resolved_segments = start_segments + target_segments).include? DOT_DOT
+      unresolved_segments, resolved_segments = resolved_segments, []
+      if jail
+        jail_segments, _ = partition_path jail unless jail_segments
+        warned = false
+        unresolved_segments.each do |segment|
+          if segment == DOT_DOT
+            if resolved_segments.size > jail_segments.size
+              resolved_segments.pop
+            elsif opts.fetch :recover, true
+              unless warned
+                logger.warn %(#{opts[:target_name] || 'path'} has illegal reference to ancestor of jail; recovering automatically)
+                warned = true
+              end
+            else
+              raise ::SecurityError, %(#{opts[:target_name] || 'path'} #{target} refers to location outside jail: #{jail} (disallowed in safe mode))
+            end
+          else
+            resolved_segments << segment
           end
-        else
-          resolved_segments.pop
         end
       else
-        resolved_segments << segment
+        unresolved_segments.each do |segment|
+          segment == DOT_DOT ? resolved_segments.pop : resolved_segments << segment
+        end
       end
     end
 
-    join_path resolved_segments, jail_root
+    if recheck
+      target_path = join_path resolved_segments, jail_root
+      if descends_from? target_path, jail
+        target_path
+      elsif opts.fetch :recover, true
+        logger.warn %(#{opts[:target_name] || 'path'} is outside of jail; recovering automatically)
+        jail_segments, _ = partition_path jail unless jail_segments
+        join_path jail_segments + target_segments, jail_root
+      else
+        raise ::SecurityError, %(#{opts[:target_name] || 'path'} #{target} is outside of jail: #{jail} (disallowed in safe mode))
+      end
+    else
+      join_path resolved_segments, jail_root
+    end
   end
 
   # Public: Resolve a web path from the target and start paths.
@@ -460,7 +484,7 @@ class PathResolver
     #  end
     #end
 
-    target_segments, target_root, _ = partition_path target, true
+    target_segments, target_root = partition_path target, true
     resolved_segments = []
     target_segments.each do |segment|
       if segment == DOT_DOT
@@ -484,22 +508,5 @@ class PathResolver
 
     uri_prefix ? %(#{uri_prefix}#{resolved_path}) : resolved_path
   end
-
-  # Public: Calculate the relative path to this absolute filename from the specified base directory
-  #
-  # If either the filename or the base_directory are not absolute paths, or the
-  # filename is not contained within the base directory, no work is done.
-  #
-  # filename       - [String] an absolute filename.
-  # base_directory - [String] an absolute base directory.
-  #
-  # Return the [String] relative path of the filename calculated from the base directory.
-  def relative_path filename, base_directory
-    if (root? filename) && (filename.start_with? base_directory)
-      filename.slice base_directory.length + 1, filename.length
-    else
-      filename
-    end
-  end
 end
 end