p4_web_api 2014.2.0.pre1

data/lib/p4_web_api/auth.rb

@@ -0,0 +1,268 @@
+# Copyright (c) 2014 Perforce Software, Inc.  All rights reserved.
+# vim:ts=2:sw=2:et:si:ai:
+
+require 'fileutils'
+require 'json'
+require 'pathname'
+require 'securerandom'
+
+require_relative 'p4_util'
+
+module P4WebAPI
+  # Sinatra Middleware component to take the HTTP Basic authentication request
+  # and pass that along to the internal P4WebAPI::Auth class methods
+  class AuthMiddleware
+    def initialize(app, options = {})
+      @app = app
+      @unauthenticated_paths = []
+      if options[:unauthenticated_paths]
+        @unauthenticated_paths = options[:unauthenticated_paths]
+      end
+      @settings = options[:settings]
+    end
+
+    def call(env)
+      return @app.call(env) if unauthenticated_path?(env)
+
+      auth = Rack::Auth::Basic::Request.new(env)
+      if auth.provided? &&
+         auth.basic? &&
+         P4WebAPI::Auth.credentials_valid?(auth.credentials, @settings)
+        env['AUTH_CREDENTIALS'] = auth.credentials
+        return @app.call(env)
+      end
+
+      unauthenticated_error
+    end
+
+    def unauthenticated_path?(env)
+      @unauthenticated_paths.include?(env['PATH_INFO'])
+    end
+
+    def unauthenticated_error
+      [
+        403,
+        { 'Content-Type' => 'text/plain',
+          'Content-Length' => '0',
+          'WWW-Authenticate' => 'Basic realm="Perforce Web API"' },
+        []
+      ]
+    end
+  end
+
+  # "Session" handling that basically uses Perforce on the backend and stores
+  # the p4 ticket in a GUID file. We then pass the GUID around 'publicly' since
+  # that's really only relevant to this one instance. We can then fetch the
+  # p4 ticket and pass that to other services internally without "exposing" it.
+  module Auth
+    # Double checks that really only the current user can write to the token
+    # directory. If it doesn't exist, we just print warnings to stdout.
+    #
+    # These checks are only intended to work on Linux and OS X.
+    def self.validate_token_dir(token_dir)
+      warn_if_tmp_dir(token_dir)
+
+      return unless File.exist?(token_dir)
+
+      if !File.owned?(token_dir)
+        puts "The current user does not own security token dir: #{token_dir}"
+      else
+        mode = File.stat(token_dir).mode
+        warn_illegal_privileges(mode, token_dir)
+      end
+    end
+
+    # If the login/password combination is valid, we'll create a new session and
+    # return the session ID (which is just a GUID).
+    #
+    # This assumes that the p4 connection already has the user name set.
+    #
+    # If the password is a ticket, that'll be stored as is. If it's a password
+    # (currently determined if it's not a 32 character alphanumeric string)
+    # we'll create a ticket and store that.
+    #
+    # Settings is the Sinatra application configuration.
+    def self.create_session(p4, password, settings)
+      ticket = nil
+
+      if P4Util.p4_ticket?(password)
+        ticket = password
+      else
+        ticket = ticket_from_login(p4)
+      end
+
+      return if ticket.nil?
+
+      results = p4.run_user('-o')
+
+      save_token(user_info(p4, results, ticket), settings)
+    end
+
+    # Saves the information stored in the user_info hash to a new randomly
+    # generated ticket file, and returns that new ticket file's name.
+    #
+    # user_info should have the following values:
+    # * login
+    # * email
+    # * full_name
+    # * ticket
+    def self.save_token(user_info, settings)
+      unless File.directory?(settings.token_path)
+        Pathname.new(settings.token_path).mkpath
+        FileUtils.chmod(0700, settings.token_path)
+      end
+
+      token = SecureRandom.uuid
+      token_path = Pathname.new(settings.token_path) + token
+
+      File.open(token_path, 'w', 0600) do |file|
+        file.write(JSON.generate(user_info))
+      end
+
+      token
+    end
+
+    # Removes the session file
+    #
+    # Assumes blindly that we're supposed to be able to do this. The caller
+    # should ensure that the token is deletable.
+    def self.delete_session(token, settings)
+      token_path = Pathname.new(settings.token_path) + token
+      File.delete(token_path) if File.exist?(token_path)
+    end
+
+    # Takes an array with [login, password], and returns true if the password
+    # is a legal token for that login, or looks like a p4 ticket.
+    def self.credentials_valid?(credentials, settings)
+      login = credentials.first
+      password = credentials.last
+      # Can't really determine much at this point, just return true. If we're
+      # a token, it's a UUID and we'll learn more about that later.
+      return true unless P4Util.uuid?(password)
+
+      user_info = read_token(password, settings)
+      if user_info
+        return user_info['login'] == login
+      else
+        false
+      end
+    end
+
+    def self.read_token(token, settings)
+      token_path = Pathname.new(settings.token_path) + token
+      if File.exist?(token_path)
+        File.open(token_path, 'r') do |file|
+          return JSON.parse(file.read)
+        end
+      end
+      nil
+    end
+
+    private
+
+    def self.warn_if_tmp_dir(token_dir)
+      if token_dir.start_with?('/tmp')
+        puts "Your token directory is using the default '/tmp' location, "\
+          'please reconfigure to a reliable location'
+      end
+    end
+
+    def self.warn_illegal_privileges(mode, token_dir)
+      warn_unless_user_rwx(mode, token_dir)
+      warn_no_group_write(mode, token_dir)
+      warn_no_group_read(mode, token_dir)
+      warn_no_group_execute(mode, token_dir)
+      warn_no_other_write(mode, token_dir)
+      warn_no_other_read(mode, token_dir)
+      warn_no_other_execute(mode, token_dir)
+    end
+
+    # Check owner read/write/execute - should all be there
+    def self.warn_unless_user_rwx(mode, token_dir)
+      unless (mode & 0400 == 0400) &&
+             (mode & 0200 == 0200) &&
+             (mode & 0100 == 0100)
+        puts "The token_path '#{token_dir}' should allow the owner read, "\
+          'write and execute privileges'
+      end
+    end
+
+    def self.warn_no_group_write(mode, token_dir)
+      if (mode & 0040 == 0040)
+        puts "The token_path '#{token_dir}' should not have group write access"
+      end
+    end
+
+    def self.warn_no_group_read(mode, token_dir)
+      if (mode & 0020 == 0020)
+        puts "The token_path '#{token_dir}' should not have group read access"
+      end
+    end
+
+    def self.warn_no_group_execute(mode, token_dir)
+      if (mode & 0010 == 0010)
+        puts "The token_path '#{token_dir}' should not have group "\
+          'execute access'
+      end
+    end
+
+    def self.warn_no_other_write(mode, token_dir)
+      if (mode & 0004 == 0004)
+        puts "The token_path '#{token_dir}' should not have other write access"
+      end
+    end
+
+    def self.warn_no_other_read(mode, token_dir)
+      if (mode & 0002 == 0002)
+        puts "The token_path '#{token_dir}' should not have other read access"
+      end
+    end
+
+    def self.warn_no_other_execute(mode, token_dir)
+      if (mode & 0001 == 0001)
+        puts "The token_path '#{token_dir}' should not have other "\
+          'execute access'
+      end
+    end
+
+    # We want special error handling here to return 4xx codes instead of 5xx
+    # in the face of an invalid password. Temporarily drop to lowest
+    # exception level, and just return nil when login doesn't work.
+    def self.ticket_from_login(p4)
+      results = nil
+      p4.at_exception_level(P4::RAISE_NONE) do
+        results = p4.run_login('-p')
+      end
+
+      auth_ok = raise_unless_auth_error(p4)
+
+      if !auth_ok
+        nil
+      else
+        p4.password = results[0]
+      end
+    end
+
+    def self.raise_unless_auth_error(p4)
+      if P4Util.error?(p4)
+        msg = p4.messages[0]
+        if msg.msgid == 7205 || # invalid user
+           msg.msgid == 7206 # invalid password
+          return false
+        else
+          P4Util.raise_error(p4)
+        end
+      end
+      true
+    end
+
+    def self.user_info(p4, results, ticket)
+      {
+        login: p4.user,
+        email: results[0]['Email'],
+        full_name: results[0]['FullName'],
+        ticket: ticket
+      }
+    end
+  end
+end

data/lib/p4_web_api/p4_error.rb

@@ -0,0 +1,36 @@
+# vim:ts=2:sw=2:et:si:ai:
+# The API sends back messages via the p4.messages attribute if there was an
+# error with the last command. We will often convert that to this exception,
+# which will be formatted into JSON.
+require 'P4'
+
+module P4WebAPI
+  # Any error we get from the Perforce server is generally encapsulated in
+  # a P4Error, which allows us to get some basic diagnostic information from
+  # the Perforce server out to the user.
+  class P4Error < RuntimeError
+    # All error codes must be greater than this number.
+    ERROR_CODE_BASE     = 15_360
+
+    attr_accessor :message_code, :message_severity, :message_text
+
+    # Class method to create a valid P4Error object from a simple
+    # string. Used when we get errors for which no P4::Message object
+    # is available.
+    def self.default_error(message_text)
+      P4Error.new(ERROR_CODE_BASE,
+                  P4::E_FAILED,
+                  message_text)
+    end
+
+    def initialize(code, severity, text)
+      @message_code     = code
+      @message_severity = severity
+      @message_text     = text
+    end
+
+    def to_s
+      @message_text
+    end
+  end
+end

data/lib/p4_web_api/p4_util.rb

@@ -0,0 +1,417 @@
+# Copyright (c) 2014 Perforce Software, Inc.  All rights reserved.
+#
+# vim:ts=2:sw=2:et:si:ai:
+#
+# p4_util.rb
+#
+#
+
+require 'date'
+require 'ostruct'
+require 'P4'
+
+require_relative 'p4_error'
+
+module P4WebAPI
+  # Namespace for p4ruby conventions used in the P4 Web API.
+  module P4Util
+    PROPERTIES = [
+      :password, :port, :user, :api_level, :charset, :client,
+      :host, :handler, :maxlocktime, :maxresults, :maxscanrows, :prog,
+      :ticketfile
+    ]
+
+    # Creates your p4 connection using some common forms.
+    #
+    # If you call open with a block, this will call connect before your block
+    # executes, and disconnect afterwards.
+    #
+    # If you do not call open with a block, it is up to the caller to connect
+    # and disconnect. (It's assumed you are calling w/o a block because you want
+    # to manage when the connection actually needs to happen.)
+    def self.open(options = {})
+      p4 = create_p4(options)
+
+      # Again, if we're calling using the block, we'll connect and disconnect.
+      # Otherwise, just return the created p4 object.
+      if block_given?
+        begin
+          p4.connect
+          yield p4
+        rescue P4Exception
+          raise make_p4_error(p4)
+        end
+      else
+        return p4
+      end
+    ensure
+      p4.disconnect if block_given? && p4 && p4.connected?
+    end
+
+    # Check for P4 errors
+    def self.error?(p4)
+      !p4.errors.empty?
+    end
+
+    # Raise an exception if necessary on a P4 Error
+    def self.raise_error(p4)
+      err = p4.messages.find { |m| m.severity > 2 }
+      fail P4WebAPI::P4Error.new(err.msgid, err.severity, err.to_s)
+    end
+
+    # Returns true if the string looks like a Perforce authentication ticket.
+    def self.p4_ticket?(str)
+      /^[a-zA-Z0-9]{32,}$/.match(str) != nil
+    end
+
+    # We only count uuids that were returned via SecureRandom.uuid used to
+    # generate internal security tokens.
+    def self.uuid?(str)
+      /^[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}$/
+        .match(str)
+    end
+
+    def self.singular(plural)
+      matches = {
+        branches: 'branch',
+        clients: 'client',
+        depots: 'depot',
+        groups: 'group',
+        jobs: 'job',
+        labels:  'label',
+        protects: 'protect',
+        servers: 'server',
+        streams: 'stream',
+        triggers: 'trigger',
+        users: 'user'
+      }
+      matches[plural.to_sym]
+    end
+
+    # Data 'normalization'
+    #
+    # A very annoying aspect of our tagged output is that it often is *slightly*
+    # different between 'plural' and spec forms. This logic is made available
+    # as an option in this API
+
+    BRANCHES_MAP = {
+      'branch' => 'Branch'
+    }
+    BRANCHES_DATES = %w(Update Access)
+
+    CHANGES_MAP = {
+      'path' => 'Path',
+      'change' => 'Change',
+      'time' => 'Date',
+      'client' => 'Client',
+      'user' => 'User',
+      'status' => 'Status',
+      'type' => 'Type',
+      'changeType' => 'Type',
+      'desc' => 'Description'
+    }
+    DESCRIBES_MAP = CHANGES_MAP
+    CHANGES_DATES = ['Date']
+
+    CLIENTS_MAP = {
+      'client' => 'Client'
+    }
+    CLIENTS_DATES = %w(Update Access)
+
+    DEPOTS_MAP = {
+      'name' => 'Depot',
+      'time' => 'Date',
+      'type' => 'Type',
+      'map' => 'Map',
+      'desc' => 'Description'
+    }
+    DEPOTS_DATES = ['Date']
+
+    DIRS_MAP = {
+      'dir' => 'Dir'
+    }
+
+    FILES_MAP = {
+      'depotFile' => 'DepotFile',
+      'rev' => 'Revision',
+      'change' => 'Change',
+      'action' => 'Action',
+      'type' => 'Type',
+      'time' => 'Date'
+    }
+    FILES_DATES = %w(Date)
+
+    GROUPS_MAP = {
+      'group' => 'Group',
+      'maxResults' => 'MaxResults',
+      'maxScanRows' => 'MaxScanRows',
+      'maxLockTime' => 'MaxLockTime',
+      'timeout' => 'Timeout',
+      'desc' => 'Description',
+      'user' => 'User',
+      'isSubGroup' => 'IsSubGroup',
+      'isOwner' => 'IsOwner',
+      'isUser' => 'IsUser',
+      'passTimeout' => 'PasswordTimeout'
+    }
+
+    JOBS_MAP = {}
+    JOBS_DATES = %w(Date)
+
+    LABELS_MAP = {
+      'label' => 'Label'
+    }
+    LABELS_DATES = %w(Update Access)
+
+    # This isn't supported but kept here for reference. We *might* support this.
+    # OPENED_MAP = {
+    #     'change' => 'Change',
+    #     'client' => 'Client',
+    #     'user' => 'User'
+    # }
+
+    STREAMS_MAP = {
+      'desc' => 'Description'
+    }
+    STREAMS_DATES = %w(Update Access)
+
+    USERS_MAP = {
+      'passwordChange' => 'PasswordChange'
+    }
+    USERS_DATES = %w(Update Access PasswordChange)
+
+    # For each 'spec type' returns a function that will ensure that:
+    # - case is consistent between different return calls, prefer 'spec' types
+    # - dates are returned
+    #
+    # Parameters:
+    # - spec_type is the 'plural' form of spec class, e.g., 'users', 'clients'
+    # - offset is the current server offset, retrieve this via 'p4 info' command
+    #
+    # rubocop:disable Metrics/CyclomaticComplexity
+    def self.normalizer(spec_type, offset)
+      case spec_type
+      when 'branches'
+        make_normalizer(BRANCHES_MAP, offset, BRANCHES_DATES)
+      when 'changes'
+        make_normalizer(CHANGES_MAP, offset, CHANGES_DATES)
+      when 'clients'
+        make_normalizer(CLIENTS_MAP, offset, CLIENTS_DATES)
+      when 'depots'
+        make_normalizer(DEPOTS_MAP, offset, DEPOTS_DATES)
+      when 'dirs'
+        make_normalizer(DIRS_MAP, offset)
+      when 'files'
+        make_normalizer(FILES_MAP, offset, FILES_DATES)
+      when 'groups'
+        date_and_case = make_normalizer(GROUPS_MAP, offset)
+        lambda do |results|
+          results = date_and_case.call(results)
+          P4Util.replace_unset_with_0(results)
+          results
+        end
+      when 'jobs'
+        make_normalizer(JOBS_MAP, offset, JOBS_DATES)
+      when 'labels'
+        make_normalizer(LABELS_MAP, offset, LABELS_DATES)
+      when 'streams'
+        make_normalizer(STREAMS_MAP, offset, STREAMS_DATES)
+      when 'users'
+        make_normalizer(USERS_MAP, offset, USERS_DATES)
+      else
+        # By default, do no translation
+        return ->(x) { x }
+      end
+    end
+
+    def self.make_normalizer(field_map, offset, date_fields = nil)
+      lambda do |results|
+        return unless results
+
+        # We need to ignore any instances of P4::Spec since that will 'validate'
+        # fields on it's accessor methods
+        results.map! do |result|
+          if result.class <= P4::Spec
+            spec = result
+            result = Hash.new
+            result.merge!(spec)
+          else
+            result
+          end
+        end
+
+        results.each do |result|
+          update_fields(field_map, result)
+          update_dates(date_fields, result, offset)
+        end
+        results
+      end
+    end
+
+    # These are 'single values' of properties of Group objects we use while
+    # collating them.
+    GROUP_PROPERTIES = %w(
+      Group MaxResults MaxScanRows MaxLockTime Timeout PasswordTimeout
+    )
+
+    # Will apply the normalizer to set up a consistent field naming and date
+    # format, but then 'collates' the output into a single list of 'groups'.
+    #
+    # The groups output is kind of funny, because it basically lists users,
+    # with group access fields. It's very non-obvious, and in the end, most
+    # clients will need to run logic like this anyway.
+    def self.collate_group_results(results)
+      collated = results.group_by { |x| x['Group'] }
+      updated = collated.map do |_key, items|
+        # The first item sets most of the values, we then figure out array
+        # subvalues
+
+        group = {}
+        GROUP_PROPERTIES.each do |p|
+          group[p] = items.first[p] if items.first.key?(p)
+        end
+
+        group['Users'] =
+            items.find_all { |x| x['IsUser'] == '1' }.map { |x| x['User'] }
+
+        group['Subgroups'] =
+            items.find_all { |x| x['IsSubGroup'] == '1' }.map { |x| x['User'] }
+
+        group['Owners'] =
+            items.find_all { |x| x['IsOwner'] == '1' }.map { |x| x['User'] }
+
+        group
+      end
+
+      results.replace(updated)
+    end
+
+    def self.replace_unset_with_0(results)
+      results.each do |r|
+        r.each_key { |k| r[k] = '0' if r[k] == 'unset' }
+      end
+    end
+
+    # Returns true if .to_i will actually convert this string to an integer
+    def self.i?(str)
+      (str =~ /\A[-+]?\d+\z/)
+    end
+
+    # Returns true if we can parse the string as a date
+    def self.date_str?(str)
+      Date.parse(str) rescue false
+    end
+
+    # In general we get dates without any offset information, which has to be
+    # retrieved via the serverDate field from 'p4 info'
+    def self.p4_date_to_i(offset, p4date)
+      DateTime.parse("#{p4date} #{offset}").to_time.to_i
+    end
+
+    def self.p4_date_offset(str)
+      DateTime.parse(str).zone
+    end
+
+    def self.resolve_host(env, settings)
+      if env.key?('P4_HOST') && settings.allow_env_p4_config
+        env['P4_HOST']
+      else
+        settings.p4['host']
+      end
+    end
+
+    def self.resolve_port(env, settings)
+      if env.key?('P4_PORT') && settings.allow_env_p4_config
+        env['P4_PORT']
+      else
+        settings.p4['port']
+      end
+    end
+
+    def self.resolve_charset(env, settings)
+      if env.key?('P4_CHARSET') && settings.allow_env_p4_config
+        env['P4_CHARSET']
+      else
+        settings.p4['charset'] if settings.p4.key?('charset')
+      end
+    end
+
+    def self.resolve_password(env, settings)
+      password = env['AUTH_CREDENTIALS'].last
+      if !P4Util.uuid?(password)
+        password
+      else
+        P4WebAPI::Auth.read_token(password, settings)['ticket']
+      end
+    end
+
+    private
+
+    def self.create_p4(options)
+      p4 = P4.new
+
+      init_p4(p4)
+
+      PROPERTIES.each do|key|
+        p4.method(key.to_s + '=').call(options[key]) if options[key]
+      end
+
+      # From the WTF department, if you think you don't want a charset set,
+      # make damn sure P4Ruby isn't going to get confused.
+      p4.charset = nil if p4.charset == 'none'
+
+      # Make P4Ruby only raise exceptions if there are errors. Warnings
+      # (such as 'no such file(s)' don't get the same treatment.
+      p4.exception_level = P4::RAISE_ERRORS
+
+      p4
+    end
+
+    # Before we do anything, clear out any environment variables that may have
+    # leaked in from your environment
+    #
+    # Some of our HTTP APIs (e.g, Git Fusion) *do* utilize environment setups
+    # for a system user, that may be installed alongside this API. We want this
+    # system to always explicitly state which configuration to use. (So, it's
+    # not just a concern of our development environments.)
+    def self.init_p4(p4)
+      p4.client = 'invalid'
+      p4.port = ''
+      p4.host = ''
+      p4.password = ''
+    end
+
+    def self.make_p4_error(p4)
+      if p4.messages && p4.messages.first
+        m = p4.messages.first
+        P4WebAPI::P4Error.new(m.msgid, m.severity, m.to_s)
+      else
+        P4WebAPI::P4Error.default_error($ERROR_INFO.to_s)
+      end
+    end
+
+    def self.update_fields(field_map, result)
+      field_map.each_key do |key|
+        next unless result.key?(key)
+        val = result[key]
+        result.delete(key)
+        result[field_map[key]] = val
+      end
+    end
+
+    # Ensures that all dates looks like epoch second (integer) times
+    def self.update_dates(date_fields, result, offset)
+      if date_fields
+        date_fields.each do |date_key|
+          next unless result.key?(date_key)
+          val = result[date_key]
+          if i?(val)
+            result[date_key] = val.to_i
+          elsif date_str?(val)
+            result[date_key] = p4_date_to_i(offset, val)
+          end
+        end
+      end
+    end
+  end
+end