razorrisk-cassini-common 0.26.24

data/lib/razor_risk/sinatra/helpers/check_auth_helper.rb

@@ -0,0 +1,209 @@
+# encoding: UTF-8
+
+# ######################################################################## #
+# File:         razor_risk/sinatra/helpers/check_auth_helper.rb
+#
+# Purpose:      Definition of the Sinatra helper CheckAuthHelper module,
+#               which provides Cassini security model checking via the
+#               +check_auth+ instance method
+#
+# Created:      1st December 2017
+# Updated:      20th February 2018
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2017-2018, Razor Risk Technologies Pty Ltd
+# All rights reserved.
+#
+# ######################################################################## #
+
+
+# ##########################################################################
+# requires
+
+require 'razor_risk/cassini/authorisation'
+require 'razor_risk/cassini/constants'
+require 'razor_risk/cassini/header_functions'
+require 'razor_risk/core/diagnostics/logger'
+
+require 'xqsr3/quality/parameter_checking'
+
+require 'sinatra/base'
+
+# ##########################################################################
+# module
+
+module RazorRisk
+module Sinatra
+module Helpers
+
+# ##########################################################################
+# CheckAuthHelper
+
+module CheckAuthHelper
+
+    include Cassini::Authorisation::HeaderHelpers
+    include Cassini::HeaderFunctions
+    include ::RazorRisk::Core::Diagnostics::Logger
+
+    include ::Xqsr3::Quality::ParameterChecking
+
+    private
+
+    HTTP_AUTHORIZATION = ::RazorRisk::Cassini::Constants::HTTP_AUTHORIZATION
+    public
+
+    RECOGNISED_AUTHENTICATION_SCHEMES = %w{ none basic authorisation_only jwt }.map { |v| v.to_sym }
+
+    RECOGNISED_ALGORITHMS = %w{ HS256 SHA256 AES-256-CBC }
+
+    # Checks the authentication information for one of the four accepted
+    # schemes - None, Basic, Authorisation-only (Razor Risk-specific),and
+    # JWT.
+    #
+    # @param env [::Hash] The request's +env+ hash.
+    # @param auth_scheme [::Symbol] The authorisation scheme.
+    # @param options [::Hash] The options hash.
+    #
+    # @option options [Boolean] :credentials (false) When true the function
+    #   will return the credentials, if they can be obtained.
+    # @option options [Boolean] :halt_unless_auth (true) If true the
+    #   function will invoke Sinatra's +halt+ with 401 when the authorisation
+    #   field +HTTP_AUTHORIZATION+ is not present.
+    # @option options [Object] :auth_sentinel The value returned if
+    #   +:halt_unless_auth+ is false.
+    # @option options [::String, Array<::String>] :auth_param_name
+    #   ('HTTP_AUTHORIZATION') The authorisation parameter name(s).
+    # @option options [::String, ::Proc] :jwt_secret The JWT secret, or a
+    #   lambda from which to obtain one, when +auth_scheme+ is +:jwt+.
+    # @option options [Boolean] :halt_unless_cred (true) If true the function
+    #   will invoke Sinatra's +halt+ with 401 when the authorisation
+    #   information does not contain valid credentials.
+    # @option options [Object] :cred_sentinel The value returned if
+    #   +:halt_unless_cred+ is true.
+    #
+    #
+    # @return [Array<::String>] If option +:credentials+ and credentials can
+    #   be obtained, returns an array containing the credentials appropriate
+    #   for the specified +auth_sheme+.
+    # @return [true] If not option +:credentials+ and credentials can be
+    #   obtained.
+    # @return [Object] Returns the value of the +:auth_sentinel+ if
+    #   +:halt_unless_auth+ is false and the auth header is not present.
+    # @return [Object] Returns the value of the +:cred_sentinel+ if
+    #   +:halt_unless_cred+ is false and no credentials could be obtained.
+    #
+    def check_auth env, auth_scheme, **options
+
+        trace ParamNames[ :env, :auth_scheme, :options ], env, auth_scheme, options
+
+        check_param env, 'env', type: ::Hash
+        check_param auth_scheme, 'auth_scheme', type: ::Symbol, values: RECOGNISED_AUTHENTICATION_SCHEMES
+        check_param options, 'options', type: ::Hash
+
+        check_param options[:credentials], 'credentials', treat_as_option: true, types: [ ::FalseClass, ::TrueClass ], allow_nil: true
+        check_param options[:halt_unless_auth], 'halt_unless_auth', treat_as_option: true, types: [ ::FalseClass, ::TrueClass ], allow_nil: true
+        check_param options[:auth_sentinel], 'auth_sentinel', treat_as_option: true, allow_nil: true
+        check_param options[:auth_param_name], 'auth_param_name', treat_as_option: true, types: [ ::String, [ ::String] ], allow_nil: true
+        check_param options[:jwt_secret], 'jwt_secret', treat_as_option: true, types: [ ::String, ::Proc ], allow_nil: :jwt != auth_scheme
+        check_param options[:halt_unless_cred], 'halt_unless_auth', treat_as_option: true, types: [ ::FalseClass, ::TrueClass ], allow_nil: true
+
+
+        options = {
+
+            auth_param_name: HTTP_AUTHORIZATION,
+            credentials: false,
+            halt_unless_auth: true,
+            halt_unless_cred: true,
+        }.merge options
+
+
+        auth = nil
+
+        auth_param_name =   options[:auth_param_name] || HTTP_AUTHORIZATION
+        case auth_param_name
+        when ::Array
+
+            auth_param_name.each do |name|
+
+                break if auth = env[name]
+            end
+        else
+
+            # will be a ::String
+            auth = env[auth_param_name]
+        end
+
+
+        log :debug4, "auth(#{auth.class})='#{auth}'"
+
+
+        unless auth || :none == auth_scheme
+
+            return options[:auth_sentinel] unless options[:halt_unless_auth]
+            halt 401, make_WWW_auth_header(auth_scheme), 'Missing or invalid authenticate header'
+        end
+
+
+        return true unless options[:credentials]
+
+
+        credentials = nil
+
+        case auth_scheme
+        when :none
+
+            credentials = []
+        when :basic
+
+            credentials = credentials_from_Basic auth, nil: true
+        when :authorisation_only, :authorization_only
+
+            credentials = credentials_from_AuthorisationOnly(auth)
+        when :jwt
+
+            jwt_secret = options[:jwt_secret]
+            jwt_secret = jwt_secret.call() if ::Proc == jwt_secret
+
+            begin
+
+                credentials = credentials_from_JWT auth, jwt_secret, nil: true
+            rescue JWT::ValidationError => x
+
+                log "exception (#{x.class}): #{x.message}"
+                halt 401, make_WWW_auth_header(auth_scheme), 'Invalid credentials'
+            rescue JWT::DecodeError => x
+
+                log "exception (#{x.class}): #{x.message}"
+                halt 401, make_WWW_auth_header(auth_scheme), 'Missing or invalid authenticate header'
+            end
+        end
+
+        return credentials if credentials
+
+        return options[:cred_sentinel] unless options[:halt_unless_cred]
+
+        halt 401, make_WWW_auth_header(auth_scheme), 'Missing or invalid authenticate header'
+    end
+
+end # module CheckAuthHelper
+
+# ##########################################################################
+# module
+
+end # module Helpers
+end # module Sinatra
+end # module RazorRisk
+
+# ##########################################################################
+# Sinatra helpers
+
+module Sinatra
+
+helpers ::RazorRisk::Sinatra::Helpers::CheckAuthHelper
+
+end # module Sinatra
+
+# ############################## end of file ############################# #
+
+

data/lib/razor_risk/sinatra/helpers/validate_accept_helper.rb

@@ -0,0 +1,69 @@
+# encoding: UTF-8
+
+# ######################################################################## #
+# File:         razor_risk/sinatra/helpers/validate_accept_helper.rb
+#
+# Purpose:      Definition of the Sinatra helper ValidateAcceptHelper
+#               module, which provides automatic 'Accept' header validation
+#
+# Created:      1st February 2018
+# Updated:      11th August 2018
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2018, Razor Risk Technologies Pty Ltd
+# All rights reserved.
+#
+# ######################################################################## #
+
+
+# ##########################################################################
+# requires
+
+require 'xqsr3/quality/parameter_checking'
+
+require 'sinatra/base'
+
+# ##########################################################################
+# module
+
+module RazorRisk
+module Sinatra
+module Helpers
+
+# ##########################################################################
+# ValidateAcceptHelper
+
+module ValidateAcceptHelper
+
+    include ::Xqsr3::Quality::ParameterChecking
+
+    def validate_accept *args, **options
+
+        rq  =   args.shift
+        ar  =   args.shift
+
+        halt 406, %Q<invalid accept type(s) (#{rq.accept.map { |a| "'#{a}'" }.join(', ')}), must be one of #{ar.map { |a| "'#{a}'" }.join(', ')}> unless ar.any? { |a| rq.accept? a }
+    end
+
+end # module ValidateAcceptHelper
+
+# ##########################################################################
+# module
+
+end # module Helpers
+end # module Sinatra
+end # module RazorRisk
+
+# ##########################################################################
+# Sinatra helpers
+
+module Sinatra
+
+helpers ::RazorRisk::Sinatra::Helpers::ValidateAcceptHelper
+
+end # module Sinatra
+
+# ############################## end of file ############################# #
+
+

data/lib/razor_risk/sinatra/helpers/validate_content_type_helper.rb

@@ -0,0 +1,74 @@
+# encoding: UTF-8
+
+# ######################################################################## #
+# File:         razor_risk/sinatra/helpers/validate_content_type_helper.rb
+#
+# Purpose:      Definition of the Sinatra helper ValidateContentTypeHelper
+#               module, which provides automatic 'Content-Type' header
+#               validation
+#
+# Created:      1st February 2018
+# Updated:      11th August 2018
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2018, Razor Risk Technologies Pty Ltd
+# All rights reserved.
+#
+# ######################################################################## #
+
+
+# ##########################################################################
+# requires
+
+require 'xqsr3/quality/parameter_checking'
+
+require 'sinatra/base'
+
+# ##########################################################################
+# module
+
+module RazorRisk
+module Sinatra
+module Helpers
+
+# ##########################################################################
+# ValidateContentTypeHelper
+
+module ValidateContentTypeHelper
+
+    include ::Xqsr3::Quality::ParameterChecking
+
+    def validate_content_type *args, **options
+
+        rq  =   args.shift
+        ar  =   args.shift
+
+        halt 415, %Q<invalid content-type '('#{rq.content_type}')', must be one of #{ar.map { |a| "'#{a}'" }.join(', ')}> unless ar.any? do |ct|
+
+            rq.content_type.start_with? ct
+        end
+    end
+
+end # module ValidateContentTypeHelper
+
+# ##########################################################################
+# module
+
+end # module Helpers
+end # module Sinatra
+end # module RazorRisk
+
+# ##########################################################################
+# Sinatra helpers
+
+module Sinatra
+
+helpers ::RazorRisk::Sinatra::Helpers::ValidateContentTypeHelper
+
+end # module Sinatra
+
+# ############################## end of file ############################# #
+
+
+

data/lib/razor_risk/sinatra/helpers/validate_query_parameters_helper.rb

@@ -0,0 +1,198 @@
+# encoding: UTF-8
+
+# ######################################################################## #
+# File:         razor_risk/sinatra/helpers/validate_query_parameters.rb
+#
+# Purpose:      Definition of the Sinatra helper
+#               ValidateQueryParametersHelper module, which provides
+#               automatic query parameter validation
+#
+# Created:      11th August 2018
+# Updated:      17th August 2018
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2018, Razor Risk Technologies Pty Ltd
+# All rights reserved.
+#
+# ######################################################################## #
+
+
+# ##########################################################################
+# requires
+
+require 'pantheios'
+require 'xqsr3/quality/parameter_checking'
+
+require 'sinatra/base'
+
+# ##########################################################################
+# module
+
+module RazorRisk
+module Sinatra
+module Helpers
+
+# ##########################################################################
+# ValidateQueryParametersHelper
+
+module ValidateQueryParametersHelper
+
+    include ::Pantheios
+
+    include ::Xqsr3::Quality::ParameterChecking
+
+    module ValidateQueryParametersHelper_Constants
+
+        SINATRA_SPECIAL_PARAMS  =   %w{
+
+            captures
+            splat
+        }
+
+    end # module ValidateQueryParametersHelper_Constants
+
+    def validate_query_parameters *args, **options
+
+        trace ParamNames[ :args, :options], args, options
+
+
+        params  =   args.shift
+        spec    =   args.shift
+        rt_vars =   args.shift || []
+
+        case spec
+        when nil
+
+            params
+        when ::Array
+
+            # interpreted as a complete list of optional parameters
+
+            unrecognised    =   params.keys - spec
+
+            unrecognised    =   unrecognised - rt_vars
+
+            unrecognised    =   unrecognised - ValidateQueryParametersHelper_Constants::SINATRA_SPECIAL_PARAMS
+
+            unless unrecognised.empty?
+
+                halt(*[ 422, {}, "One or more parameters - '#{unrecognised}' - are not supported on this route" ])
+            end
+
+            params
+        when ::Hash
+
+            # interpreted as a map of { query-parameter => [ 0+
+            # characteristics-symbols] }, where recognised characteristics are:
+            #
+            # - :allow_empty - means that the parameter value may be empty
+            #   (subject to :strip);
+            # - :required - means that the parameter must be present;
+            # - :strip - causes the parameter to be (converted to string
+            #   form and then) stripped;
+            #
+            # - :integral - causes the parameter to be converted to string;
+            #   halts(422) if the conversion fails;
+            # - :negative - requires the value to be <0; operative only if
+            #   :integral is specified;
+            # - :positive - requires the value to be >0; operative only if
+            #   :integral is specified;
+            # - :non_negative - requires the value to be >=0; operative only
+            #   if :integral is specified;
+            # - :non_positive - requires the value to be <=0; operative only
+            #   if :integral is specified;
+
+            warn "validating query parameters from a #{::Hash} spec is not supported in the current version"
+
+            unrecognised    =   params.keys - spec.keys
+
+            unrecognised    =   unrecognised - rt_vars
+
+            unrecognised    =   unrecognised - ValidateQueryParametersHelper_Constants::SINATRA_SPECIAL_PARAMS
+
+            unless unrecognised.empty?
+
+                halt(*[ 422, {}, "One or more parameters - '#{unrecognised}' - are not supported on this route" ])
+            end
+
+            validated_params = params.dup
+
+            spec.each do |k, characteristics|
+
+                next if ValidateQueryParametersHelper_Constants::SINATRA_SPECIAL_PARAMS.include?(k)
+
+                next if rt_vars.include?(k)
+
+                case v
+                when nil
+
+                    next
+                when ::Array
+
+                    ;
+                else
+
+                    characteristics = [ characteristics ]
+                end
+
+                if validated_params.has_key? k
+
+                    value   =   validated_params[k]
+
+                    value   =   value.to_s.strip if characteristics.include? :strip
+
+                    unless characteristics.include? :allow_empty
+
+                        if value.to_s.empty?
+
+                            halt(*[ 422, {}, "Query parameter '#{k}' has missing value in URI" ])
+                        end
+                    end
+
+                    if characteristics.include? :integral
+
+                        # TODO : implement integral conversion and
+                        # range-checking
+                    end
+
+                    validated_params[k] = value
+                else
+
+                    if characteristics.include? :required
+
+                        halt(*[ 422, {}, "Required query parameter '#{k}' not present in URI" ])
+                    end
+                end
+            end
+
+            validated_params
+        else
+
+
+
+            warn "#{self.class}##{__method__}() : invalid spec type - '#{spec.class}' - given - ignoring"
+        end
+    end
+
+end # module ValidateQueryParametersHelper
+
+# ##########################################################################
+# module
+
+end # module Helpers
+end # module Sinatra
+end # module RazorRisk
+
+# ##########################################################################
+# Sinatra helpers
+
+module Sinatra
+
+helpers ::RazorRisk::Sinatra::Helpers::ValidateQueryParametersHelper
+
+end # module Sinatra
+
+# ############################## end of file ############################# #
+
+

data/test/scratch/cassini/util/convert_XML.rb

@@ -0,0 +1,54 @@
+#! /usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), *(['..'] * 4), 'lib')
+
+unless $DEBUG
+
+    require 'pantheios/globals'
+    require 'pantheios/services/null_log_service'
+
+    ::Pantheios::Globals.INITIAL_SERVICE_CLASSES = [ ::Pantheios::Services::NullLogService ]
+end
+
+require 'razor_risk/cassini/util/conversion_util'
+
+require 'libclimate'
+require 'xqsr3/extensions/test/unit'
+
+require 'pp'
+
+include ::RazorRisk::Cassini::Util::ConversionUtil
+
+climate = LibCLImate::Climate.new do |cl|
+
+    cl.usage_values = '<scheme> <Hash|json> [<xml-doc-path>]'
+end
+
+r = climate.run ARGV
+
+scheme          =   r.values[0]
+output_type     =   r.values[1]
+xml_doc_path    =   r.values[2]
+
+climate.abort 'too many values; use --help for usage' if r.values[3]
+climate.abort "Output type may only be 'Hash' or 'JSON'; use --help for usage" unless output_type =~ /hash|json/i
+
+if xml_doc_path
+
+    xml_doc =   File.read(xml_doc_path)
+else
+
+    xml_doc =   $stdin.read
+end
+
+case output_type
+when /hash/i
+
+    puts convert_XML_to_Hash xml_doc, scheme: scheme.to_sym
+when /JSON/i
+
+    puts convert_XML_to_JSON xml_doc, scheme: scheme.to_sym
+else
+
+    abort "output_type may only be 'Hash' or 'JSON' but was #{output_type}"
+end