xolo-admin 1.0.0

data/lib/xolo/admin/connection.rb

@@ -0,0 +1,191 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+#
+
+# frozen_string_literal: true
+
+# main module
+module Xolo
+
+  module Admin
+
+    # connection to the xolo server from xadm
+    module Connection
+
+      # Constants
+      ##############################
+      ##############################
+
+      TIMEOUT = 300
+      OPEN_TIMEOUT = 10
+
+      PING_ROUTE = '/ping'
+      PING_RESPONSE = 'pong'
+
+      LOGIN_ROUTE = '/auth/login'
+
+      # Module methods
+      ##############################
+      ##############################
+
+      # when this module is included
+      def self.included(includer)
+        Xolo.verbose_include includer, self
+      end
+
+      # Instance Methods
+      ##############################
+      ##############################
+
+      # Authenticate to the Xolo server and get a session token
+      # (maintained by Faraday via the Xolo::Admin::CookieJar middleware)
+      #
+      ##############
+      def login(test: false)
+        return if !test && cmd_details[:no_login]
+
+        hostname = config.hostname
+        admin = config.admin
+        pw = fetch_pw
+        xadm = Xolo::Admin::EXECUTABLE_FILENAME
+
+        raise Xolo::MissingDataError, "No xolo server hostname. Please run '#{xadm} config'" unless hostname
+        raise Xolo::MissingDataError, "No xolo admin username. Please run '#{xadm} config'" unless admin
+
+        payload = { admin: admin, password: pw }
+
+        payload[:proxy_admin] = global_opts[:proxy_admin] if global_opts[:proxy_admin]
+
+        # provide the hostname to make a persistent Faraday connection object
+        # so in the future we just call server_cnx with no hostname to get the same
+        # connection object
+        resp = server_cnx.post Xolo::Admin::Connection::LOGIN_ROUTE, payload
+
+        if resp.success?
+          @logged_in = true
+          return
+        end
+
+        case resp.status
+        when 401
+          raise Xolo::AuthenticationError, resp.body[:error]
+        else
+          raise Xolo::ServerError, "#{resp.status}: #{resp.body}"
+        end
+      rescue Faraday::UnauthorizedError
+        raise Xolo::AuthenticationError, 'Invalid username or password'
+      end
+
+      # @pararm host [String] an alternate hostname to use, defaults to config.hostname
+      #
+      # @return [URI] The server base URL
+      #################
+      def server_url(host: nil)
+        @server_url = nil if host
+        return @server_url if @server_url
+
+        @server_url = URI.parse "https://#{host || config.hostname}"
+      end
+
+      # A connection for requests without any file uploads
+      #
+      # None of our GET routes expected any request body, so it doesn't matter if
+      # its set to be JSON.
+      #
+      # For our POST routes that dont upload files (e.g. setloglevel), the request
+      # body, if any, will be JSON.
+      #
+      # @param host [String] The hostname of the Xolo server. Must be provided the
+      #   first time this is called (usually for logging in)
+      #
+      # @return [Faraday::Connection]
+      ##################################
+      def server_cnx(host: nil)
+        @server_cnx = nil if host
+        return @server_cnx if @server_cnx
+
+        @server_cnx = Faraday.new(server_url(host: host)) do |cnx|
+          cnx.options[:timeout] = TIMEOUT
+          cnx.options[:open_timeout] = OPEN_TIMEOUT
+
+          cnx.request :json
+
+          cnx.use Xolo::Admin::CookieJar
+
+          cnx.response :json, parser_options: { symbolize_names: true }
+          cnx.response :raise_error
+
+          cnx.adapter :net_http
+        end
+
+        # @server_cnx.headers['X-Proxy-Admin'] = global_opts[:proxy_admin] if global_opts[:proxy_admin]
+      end
+
+      # A connection for responses that stream the progress of a long server
+      # process.
+      #
+      # @param host [String] The hostname of the Xolo server. Must be provided the
+      #   first time this is called (usually for logging in)
+      #
+      # @return [Faraday::Connection]
+      ##################################
+      def streaming_cnx(host: nil)
+        @streaming_cnx = nil if host
+        return @streaming_cnx if @streaming_cnx
+
+        # this proc every time we get a chunk, just print it to stdout
+        # and make note if any of them conain an error
+        streaming_proc = proc do |chunk, _size, _env|
+          puts chunk
+          @streaming_error ||= chunk.include? STREAMING_OUTPUT_ERROR
+        end
+
+        req_opts = { on_data: streaming_proc }
+
+        @streaming_cnx = Faraday.new(server_url(host: host), request: req_opts) do |cnx|
+          cnx.options[:timeout] = TIMEOUT
+          cnx.options[:open_timeout] = OPEN_TIMEOUT
+          cnx.use Xolo::Admin::CookieJar
+          cnx.response :raise_error
+          cnx.adapter :net_http
+        end
+      end
+
+      # A connection for POST requests with file uploads
+      #
+      # The request body will be multipart/url-encoded
+      # and authentication is required
+      #
+      # @param host [String] The hostname of the Xolo server. Must be provided the
+      #   first time this is called (usually for logging in)
+      #
+      # @return [Faraday::Connection]
+      ##################################
+      def upload_cnx(host: nil)
+        @upload_cnx = nil if host
+        return @upload_cnx if @upload_cnx
+
+        @upload_cnx = Faraday.new(server_url(host: host)) do |cnx|
+          cnx.options[:timeout] = TIMEOUT
+          cnx.options[:open_timeout] = OPEN_TIMEOUT
+
+          cnx.request :multipart
+          cnx.request :url_encoded
+
+          cnx.use Xolo::Admin::CookieJar
+
+          cnx.response :json, parser_options: { symbolize_names: true }
+          cnx.response :raise_error
+
+          cnx.adapter :net_http
+        end
+      end
+
+    end # module Connection
+
+  end # module Admin
+
+end # module Xolo

data/lib/xolo/admin/cookie_jar.rb

@@ -0,0 +1,81 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+#
+
+# frozen_string_literal: true
+
+# main module
+module Xolo
+
+  module Admin
+
+    # Faraday Middleware for storing and sending the only cookie we
+    # use with the Xolo server.
+    #
+    # See https://lostisland.github.io/faraday/#/middleware/custom-middleware
+    #
+    class CookieJar < Faraday::Middleware
+
+      # Constants
+      ##########################
+      ##########################
+
+      COOKIE_HEADER = 'Cookie'
+      SET_COOKIE_HEADER = 'set-cookie'
+      SESSION_COOKIE_NAME = 'rack.session'
+      SESSION_COOKIE_EXPIRES_NAME = 'expires'
+
+      # Class Methods
+      ##########################
+      ##########################
+
+      class << self
+
+        # runtime storage for our single cookie
+        attr_accessor :session_cookie, :session_expires
+
+      end
+
+      # Instance Methods
+      ##########################
+      ##########################
+
+      # we only send back the rack.session cookie, as long as it
+      # exists and hasn't expired (it lasts an hour)
+      #####################
+      def on_request(env)
+        return unless self.class.session_cookie && self.class.session_expires
+
+        raise Xolo::InvalidTokenError, 'Server Session Expired' if Time.now > self.class.session_expires
+
+        env[:request_headers][COOKIE_HEADER] = "#{SESSION_COOKIE_NAME}=#{self.class.session_cookie}"
+      end
+
+      # The server only ever sends one cookie,
+      # and we only care about 2 values:
+      # rack.session, and expires
+      ####################
+      def on_complete(env)
+        raw_cookie = env[:response_headers][SET_COOKIE_HEADER]
+        return unless raw_cookie
+
+        tepid_cookie = raw_cookie.split(Xolo::SEMICOLON_SEP_RE)
+        tepid_cookie.each do |part|
+          name, value = part.split('=')
+          case name
+          when SESSION_COOKIE_NAME
+            self.class.session_cookie = value
+          when SESSION_COOKIE_EXPIRES_NAME
+            self.class.session_expires = Time.parse(value).localtime
+          end
+        end
+      end
+
+    end # module Converters
+
+  end # module Admin
+
+end # module Xolo

data/lib/xolo/admin/credentials.rb

@@ -0,0 +1,212 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+#
+
+# frozen_string_literal: true
+
+# main module
+module Xolo
+
+  module Admin
+
+    # Personal credentials for users of 'xadm', stored in the login keychain
+    #
+    module Credentials
+
+      # Constants
+      ##############################
+      ##############################
+
+      # The security command
+      SEC_COMMAND = '/usr/bin/security'
+
+      # exit status when the login keychain can't be accessed because we aren't in a GUI session
+      SEC_STATUS_NO_GUI_ERROR = 36
+
+      # exit status when the keychain password provided is incorrect
+      SEC_STATUS_AUTH_ERROR = 51
+
+      # exit status when the desired item isn't found in the keychain
+      SEC_STATUS_NOT_FOUND_ERROR = 44
+
+      # The 'kind' of item in the keychain
+      XOLO_CREDS_KIND = 'Xolo::Admin::Password'
+
+      # the Service for the generic 'Xolo::Admin::Credentials' keychain entry
+      XOLO_CREDS_SVC = 'com.pixar.xolo.password'
+
+      # the Label for the generic 'Xolo::Admin::Credentials' keychain entry
+      XOLO_CREDS_LBL = '"Xolo Admin Password"'
+
+      # Module methods
+      ##############################
+      ##############################
+
+      # when this module is included
+      def self.included(includer)
+        Xolo.verbose_include includer, self
+      end
+
+      # Instance Methods
+      ##########################
+      ##########################
+
+      # If the keychain is not accessible, prompt for the password
+      #
+      # @return [String] Get the admin's password from the login keychain
+      #
+      ##############################################
+      def fetch_pw
+        return config.data_from_command_file_or_string(config.pw, enforce_secure_mode: true) if config.no_gui
+
+        cmd = ['find-generic-password']
+        cmd << '-s'
+        cmd << XOLO_CREDS_SVC
+        cmd << '-l'
+        cmd << XOLO_CREDS_LBL
+        cmd << '-w'
+        run_security(cmd.map { |i| security_escape i }.join(' '))
+
+      # If we can't access the keychain, prompt for the password. This is usually
+      # when we're running in a non-GUI session, e.g. via ssh.
+      rescue Xolo::KeychainError
+        raise unless @security_exit_status.exitstatus == SEC_STATUS_NO_GUI_ERROR
+        raise unless STDOUT.isatty
+
+        question = "Keychain not accessible.\nPlease enter the xolo admin password for #{config.admin}: "
+        highline_cli.ask(question) do |q|
+          q.echo = false
+        end
+      end
+
+      # Store an item in the default keychain
+      #
+      # @param acct [String] The username for the password.
+      #   xadm doesn't use this, it uses the admin name from the
+      #   configuration. But the keychain item requires a value here.
+      #
+      # @param pw [String] The password to store
+      #
+      # @return [String] the location where the password is stored
+      ##############################################
+      def store_pw(acct, pw)
+        # delete the item first if its there
+        delete_pw
+
+        cmd = ['add-generic-password']
+        cmd <<  '-a'
+        cmd <<  acct
+        cmd << '-s'
+        cmd << XOLO_CREDS_SVC
+        cmd << '-w'
+        cmd << pw
+        cmd << '-l'
+        cmd << XOLO_CREDS_LBL
+        cmd << '-D'
+        cmd << XOLO_CREDS_KIND
+
+        run_security(cmd.map { |i| security_escape i }.join(' '))
+      end
+
+      # delete the xolo admin password from the login keychain
+      # @return [void]
+      ##############################################
+      def delete_pw
+        cmd = ['delete-generic-password']
+        cmd << '-s'
+        cmd << XOLO_CREDS_SVC
+        cmd << '-l'
+        cmd << XOLO_CREDS_LBL
+
+        run_security(cmd.map { |i| security_escape i }.join(' '))
+      rescue Xolo::NoSuchItemError
+        nil
+      rescue RuntimeError => e
+        raise e unless e.to_s == 'No matching keychain item was found'
+
+        nil
+      end
+
+      # Run the security command in interactive mode on a given keychain,
+      # passing in a subcommand and its arguments. so that they don't appear in the
+      # `ps` output
+      #
+      # @param cmd [String] the subcommand being passed to 'security' with
+      #   all needed options. It will not be visible outide this process, so
+      #   its OK to put passwords into the options.
+      #
+      # @return [String] the stdout of the 'security' command.
+      #
+      ######
+      def run_security(cmd)
+        output = Xolo::BLANK
+        errs = Xolo::BLANK
+
+        Open3.popen3("#{SEC_COMMAND} -i") do |stdin, stdout, stderr, wait_thr|
+          # pid = wait_thr.pid # pid of the started process.
+          stdin.puts cmd
+          stdin.close
+
+          output = stdout.read
+          errs = stderr.read
+
+          @security_exit_status = wait_thr.value # Process::Status object returned.
+        end
+        # exit 44 is 'The specified item could not be found in the keychain'
+        return output.chomp if @security_exit_status.success?
+
+        case @security_exit_status.exitstatus
+        when SEC_STATUS_AUTH_ERROR
+          raise Xolo::KeychainError, 'Problem accessing login keychain. Is it locked?'
+
+        when SEC_STATUS_NOT_FOUND_ERROR
+          raise Xolo::NoSuchItemError, "No xolo admin password. Please run 'xadm config'"
+
+        else
+          errs.chomp!
+          errs =~ /: returned\s+(-?\d+)$/
+          errnum = Regexp.last_match(1)
+          desc = errnum ? security_error_desc(errnum) : errs
+          desc ||= errs
+          raise Xolo::KeychainError, "#{desc.gsub("\n", '; ')}; exit status #{@security_exit_status.exitstatus}"
+        end # case
+      end # run_security
+
+      # use `security error` to get a description of an error number
+      ##############
+      def security_error_desc(num)
+        desc = `#{SEC_COMMAND} error #{num}`
+        return if desc.include?('unknown error')
+
+        desc.chomp.split(num).last
+      rescue StandardError
+        nil
+      end
+
+      # given a string, wrap it in single quotes and escape internal single quotes
+      # and backslashes so it can be used in the interactive 'security' command
+      #
+      # @param str[String] the string to escape
+      #
+      # @return [String] the escaped string
+      ###################
+      def security_escape(str)
+        # first escape backslashes
+        str = str.to_s.gsub '\\', '\\\\\\'
+
+        # then single quotes
+        str.gsub! "'", "\\\\'"
+
+        # if other things need escaping, add them here
+
+        "'#{str}'"
+      end # security_escape
+
+    end # module Prefs
+
+  end # module Admin
+
+end # module Xolo

data/lib/xolo/admin/highline_terminal.rb

@@ -0,0 +1,81 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+#
+
+# frozen_string_literal: true
+
+# MonkeyPatch HighLine::Terminal#readline_read so that Readline
+# lines can be case-insensitive, and have a prompt.
+#
+# To use a prompt, put it in the environtment variable 'XADM_HIGHLINE_READLINE_PROMPT'
+#
+# To make the readline completion case-insensitive, set the environment
+# variable XADM_HIGHLINE_READLINE_CASE_INSENSITIVE to anything.
+#
+# This really only modifies the Regexp used for the completion_proc to make it
+# case insensitive if desired (adding an 'i' to the end)
+# and sets the prompt when calling Readline.readline
+#
+# TODO: Do this 'smartly' as with the monkeypatches in pixar-ruby-extensions
+#
+class HighLine
+
+  class Terminal
+
+    # Use readline to read one line
+    # @param question [HighLine::Question] question from where to get
+    #   autocomplete candidate strings
+    #################################
+    def readline_read(question)
+      # prep auto-completion
+      unless question.selection.empty?
+        Readline.completion_proc = lambda do |str|
+          regex = ENV['XADM_HIGHLINE_READLINE_CASE_INSENSITIVE'] ? /\A#{Regexp.escape(str)}/i : /\A#{Regexp.escape(str)}/
+          question.selection.grep(regex)
+        end
+      end
+
+      # work-around ugly readline() warnings
+      old_verbose = $VERBOSE
+      $VERBOSE    = nil
+
+      raw_answer  = run_preserving_stty do
+        Readline.readline(ENV['XADM_HIGHLINE_READLINE_PROMPT'].to_s, true)
+      end
+
+      $VERBOSE = old_verbose
+
+      raw_answer
+    end
+
+    # Get one line from terminal using default #gets method.
+    ##############################
+    # def get_line_default(highline)
+    #   raise EOFError, 'The input stream is exhausted.' if highline.track_eof? && highline.input.eof?
+
+    #   highline.output.print "#{ENV['XADM_HIGHLINE_LINE_PROMPT']}" if ENV['XADM_HIGHLINE_LINE_PROMPT']
+
+    #   highline.input.gets
+    # end
+
+  end # terminal
+
+  # # Deals with the task of "asking" a question
+  # class QuestionAsker
+
+  #   alias ask_once_real ask_once
+
+  #   # Gets just one answer, as opposed to #gather_answers
+  #   #
+  #   # @return [String] answer
+  #   def ask_once
+  #     @highline.output.print "#{ENV['XADM_HIGHLINE_LINE_PROMPT']}" if ENV['XADM_HIGHLINE_LINE_PROMPT']
+  #     ask_once_real
+  #   end
+
+  # end # question asker
+
+end