razorrisk-cassini-common 0.26.24

data/lib/razor_risk/cassini/applications/route_verb_adaptors/utilities/collection_get_helper.rb

@@ -0,0 +1,86 @@
+# encoding: UTF-8
+
+# ######################################################################## #
+# File:         razor_risk/cassini/applications/route_verb_adaptors/utilities/collection_get_helper.rb
+#
+# Purpose:      Adaptor for Portfolios microservice's collection GET verb
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2018, Razor Risk Technologies Pty Ltd
+# All rights reserved.
+#
+# ######################################################################## #
+
+
+# ##########################################################################
+# requires
+
+require 'pantheios'
+require 'xqsr3/quality/parameter_checking'
+
+module RazorRisk
+module Cassini
+module Applications
+module RouteVerbAdaptors
+module Utilities
+
+# ##########################################################################
+# modules
+
+module CollectionGetHelper
+
+    include ::Pantheios
+
+    include ::Xqsr3::Quality::ParameterChecking
+
+    # This function validates that at most of the given
+    # +search_parameter_names+ is specified in the +params+ hash, or issues
+    # a halt with a suitable message
+    #
+    # === Signature
+    #
+    # * *Parameters:*
+    #  @param +params+:: (::Hash) The verb handler adaptor's +params+ attribute.
+    #   May not be +nil+
+    #  @param +search_parameter_names+:: (::Array) The names of the query
+    #   parameters to validate
+    #  @param +options+:: (::Hash) Options
+    #
+    # * *Options:*
+    #  @option +:halt_code+:: (::Integer) Specifies the halt code to be
+    #   issued. Defaults to 422. If 0, the function does not call halt, and
+    #   instead returns +false+
+    #  @option +:message_scope+:: (::String) The scoping part of the
+    #   message. Defaults to 'invalid search specifier'. If specified as the
+    #   empty string no scoping part will be included in the halt message
+    def validate_exclusive_search_parameters params, *search_parameter_names, **options
+
+        halt_code       =   Integer(options[:halt_code] || 422)
+
+        message_scope   =   options[:message_scope] || 'invalid search specifier'
+        message_scope   +=  ': ' unless message_scope.empty?
+
+        names_present   =   search_parameter_names.select { |name| params[name] }.sort
+
+        case names_present.count
+        when 0, 1
+
+            true
+        else
+
+            halt *[ halt_code, {}, "#{message_scope}cannot specify '#{names_present[0]}' and '#{names_present[1]}' together" ]
+        end
+    end
+
+end # module CollectionGetHelper
+
+end # module Utilities
+end # module RouteVerbAdaptors
+end # module Applications
+end # module Cassini
+end # module RazorRisk
+
+# ############################## end of file ############################# #
+
+

data/lib/razor_risk/cassini/applications/securable_microservice.rb

@@ -0,0 +1,164 @@
+
+#############################################################################
+# File:     lib/razor_risk/cassini/applications/securable_microservice.rb
+#
+# Purpose:  Define the SecurableMicroservice base class
+#
+# Author:   Matthew Wilson
+#
+# Copyright (c) 2017, Razor Risk Technologies Pty Ltd
+# All rights reserved
+#
+# ##########################################################################
+
+
+require 'razor_risk/cassini/applications/microservice'
+
+require 'razor_risk/sinatra/helpers/check_auth_helper'
+
+require 'razor_risk/razor/connectivity/razor_3/razor_requester'
+
+require 'razor_risk/core/diagnostics/logger'
+
+module RazorRisk
+module Cassini
+module Applications
+
+class SecurableMicroservice < Microservice
+
+    helpers ::RazorRisk::Sinatra::Helpers::CheckAuthHelper
+    include ::RazorRisk::Core::Diagnostics::Logger
+
+    private
+
+    def self.init_service_ \
+        authentication_scheme,
+        jwt_encoding_algorithm,
+        secrets,
+        options
+
+        trace ParamNames[ :authentication_scheme, :jwt_encoding_algorithm, :secrets, :options], authentication_scheme, jwt_encoding_algorithm, secrets, options
+
+        set :authentication_scheme, authentication_scheme
+        set :jwt_encoding_algorithm, jwt_encoding_algorithm
+        set :secrets, secrets
+
+        if true == options[:auth_test_mode]
+            log :warning, "YOU ARE IN AUTHORIZATION TEST MODE! NO AUTHENTICATION WILL BE PERFORMED! THIS MUST NOT BE USED IN PRODUCTION!"
+            set :auth_test_mode, true
+        else
+            set :auth_test_mode, false
+        end
+
+        set :microservice_is_initialised, Time.now
+
+        self
+    end
+
+    public
+
+    # This must be invoked prior to activation of the application
+    #
+    # === Signature
+    #
+    # * *Parameters:*
+    #   - +host+:: [String] The host to which the application binds. May be:
+    #     +nil+, in which case no binding is performed and the Sinatra
+    #     defaults are observed; +'0.0.0.0', in which case the server will
+    #     listen on all available interfaces; a specific IP addres, in which
+    #     case the server will listen only on that address. It is recommend
+    #     that a specific address is used. Required
+    #   - +port+:: [Integer] The port on which to activate. Required
+    #   - +authentication_scheme+:: [String, Symbol] The authentication
+    #     scheme to be used. Must be one of
+    #     RECOGNISED_AUTHENTICATION_SCHEMES. Required
+    #   - +jwt_encoding_algorithm+:: [String] The algorithm that will be
+    #     used for encoding the JWT in the +:jwt+ authentication scheme.
+    #     Must be one of RECOGNISED_ALGORITHMS. Required only if
+    #     +authentication_scheme+ is +:jwt+
+    #   - +secrets+:: [Hash] An association of secrets for algorithms. Must
+    #     contain at least secrets for the algorithms specified for
+    #     +jwt_encoding_algorithm+.
+    def self.init_service \
+        host: to_nil(host_not_given_ = true),
+        port: to_nil(port_not_given_ = true),
+        authentication_scheme: to_nil(authentication_scheme_not_given_ = true),
+        jwt_encoding_algorithm: to_nil(jwt_encoding_algorithm_not_given_ = true),
+        secrets: to_nil(secrets_not_given_ = true),
+        **options
+
+        trace ParamNames[ :host, :port, :authentication_scheme, :jwt_encoding_algorithm, :secrets ], host, port, authentication_scheme, jwt_encoding_algorithm, secrets
+
+        raise ArgumentError, 'missing keyword: host' if host_not_given_
+        check_parameter host, 'host', type: ::String, allow_nil: true
+
+        raise ArgumentError, 'missing keyword: port' if port_not_given_
+        check_parameter port, 'port', type: Integer
+
+        raise ArgumentError, 'missing keyword: authentication_scheme' if authentication_scheme_not_given_
+        # check_parameter cannot types types then convert (by block) then
+        # check values in one operation, so instead convert to Symbol only
+        # if String
+        authentication_scheme = authentication_scheme.to_sym if ::String === authentication_scheme
+        check_parameter authentication_scheme, 'authentication_scheme', types: [ ::String, ::Symbol ], values: RECOGNISED_AUTHENTICATION_SCHEMES
+
+        if :jwt == authentication_scheme
+
+            if severity_logged? :debug4
+
+                log :debug4, "jwt_encoding_algorithm (#{jwt_encoding_algorithm.class})=#{jwt_encoding_algorithm}"
+            end
+
+            raise ArgumentError, 'missing keyword: jwt_encoding_algorithm' if jwt_encoding_algorithm_not_given_
+            check_parameter jwt_encoding_algorithm, 'jwt_encoding_algorithm', type: ::String, values: RECOGNISED_ALGORITHMS
+        end
+
+        init_service_ \
+            authentication_scheme,
+            jwt_encoding_algorithm,
+            secrets,
+            options
+
+        # invoke superclass
+        init_base_service host: host, port: port, **options
+    end
+
+    def self.secret algorithm
+
+        trace ParamNames[:algorithm], algorithm
+
+        return nil if algorithm.nil?
+        return nil unless settings.respond_to? :secrets
+
+        settings.secrets[algorithm.downcase]
+    end
+
+    def secret algorithm
+
+        trace ParamNames[:algorithm], algorithm
+
+        self.class.secret algorithm
+    end
+
+
+    before do
+
+        trace
+    end
+
+    # Error handler for invalid credentials.
+    error Razor::Connectivity::Razor3::RazorRequester::InvalidCredentialsException do
+        x = env['sinatra.error']
+        log :warning, "Invalid Credentials"
+        error 401, "Invalid Credentials"
+    end
+
+end # class SecurableMicroservice
+
+end # module Applications
+end # module Cassini
+end # module RazorRisk
+
+# ############################## end of file ############################# #
+
+

data/lib/razor_risk/cassini/applications/secured_microservice.rb

@@ -0,0 +1,63 @@
+
+#############################################################################
+# File:     lib/razor_risk/cassini/applications/securable_microservice.rb
+#
+# Purpose:  Define the SecurableMicroservice base class
+#
+# Author:   Matthew Wilson
+#
+# Copyright (c) 2017, Razor Risk Technologies Pty Ltd
+# All rights reserved
+#
+# ##########################################################################
+
+
+require 'razor_risk/cassini/applications/securable_microservice'
+require 'razor_risk/core/diagnostics/logger'
+
+module RazorRisk
+module Cassini
+module Applications
+
+# A refinement of the SecurableMicroservice class that checks authorisation
+# for every request (in the before handler) and exposes the obtained
+# credentials (in an authentication scheme-dependent form) in the
+# +credentials+ attribute
+class SecuredMicroservice < SecurableMicroservice
+    include ::RazorRisk::Core::Diagnostics::Logger
+    before do
+
+        trace
+
+        # because all routes in this class are authorised, we can do the
+        # check in one place
+
+        log :informational, 'verifying authentication'
+
+        options     =   {
+
+            credentials: true,
+        }
+
+        if :jwt == settings.authentication_scheme
+            options[:jwt_secret] = secret(settings.jwt_encoding_algorithm)
+        end
+
+        @credentials = check_auth env, settings.authentication_scheme, **options
+
+        log :debug4, "@credentials(#{@credentials.class})='#{@credentials}'"
+    end
+
+    attr_reader :credentials
+
+    private
+
+end # class SecuredMicroservice
+
+end # module Applications
+end # module Cassini
+end # module RazorRisk
+
+# ############################## end of file ############################# #
+
+

data/lib/razor_risk/cassini/applications/unsecured_microservice.rb

@@ -0,0 +1,77 @@
+
+#############################################################################
+# File:     lib/razor_risk/cassini/applications/unsecured_microservice.rb
+#
+# Purpose:  Define the UnsecuredMicroservice base class
+#
+# Author:   Matthew Wilson
+#
+# Copyright (c) 2017, Razor Risk Technologies Pty Ltd
+# All rights reserved
+#
+# ##########################################################################
+
+
+require 'razor_risk/cassini/applications/microservice'
+
+module RazorRisk
+module Cassini
+module Applications
+
+class UnsecuredMicroservice < Microservice
+
+    private
+
+    def self.init_service_ \
+        options
+
+        trace
+
+        set :microservice_is_initialised, Time.now
+
+        self
+    end
+
+    public
+
+    # This must be invoked prior to activation of the application
+    #
+    # === Signature
+    #
+    # * *Parameters:*
+    #   - +host+:: [String] The host to which the application binds. May be:
+    #     +nil+, in which case no binding is performed and the Sinatra
+    #     defaults are observed; +'0.0.0.0', in which case the server will
+    #     listen on all available interfaces; a specific IP addres, in which
+    #     case the server will listen only on that address. It is recommend
+    #     that a specific address is used. Required
+    #   - +port+:: [Integer] The port on which to activate. Required
+    def self.init_service \
+        host: to_nil(host_not_given_ = true),
+        port: to_nil(port_not_given_ = true),
+        **options
+
+        trace ParamNames[:host, :port, ], host, port
+
+        raise ArgumentError, 'missing keyword: host' if host_not_given_
+        check_parameter host, 'host', type: ::String, allow_nil: true
+
+        raise ArgumentError, 'missing keyword: port' if port_not_given_
+        check_parameter port, 'port', type: Integer
+
+        init_service_ \
+            options
+
+        # invoke superclass
+        init_base_service host: host, port: port, **options
+    end
+
+end # class UnsecuredMicroservice
+
+end # module Applications
+end # module Cassini
+end # module RazorRisk
+
+# ############################## end of file ############################# #
+
+

data/lib/razor_risk/cassini/authorisation/header_helpers.rb

@@ -0,0 +1,271 @@
+# encoding: UTF-8
+
+# ######################################################################## #
+# File:         razor_risk/cassini/authorisation/header_helpers.rb
+#
+# Purpose:      ::RazorRisk::Cassini::Authorisation::HeaderHelpers module
+#
+# Created:      16th February 2018
+# Updated:      4th March 2018
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2018, Razor Risk Technologies Pty Ltd
+# All rights reserved.
+#
+# ######################################################################## #
+
+
+# ##########################################################################
+# requires
+
+require 'razor_risk/core/cryptography/ciphers/aes_cipher'
+require 'razor_risk/core/diagnostics/logger'
+
+require 'pantheios'
+require 'xqsr3/quality/parameter_checking'
+
+require 'jwt'
+
+require 'json'
+
+=begin
+=end
+
+module RazorRisk
+module Cassini
+module Authorisation
+
+module HeaderHelpers
+
+    include ::Pantheios
+    include ::Xqsr3::Quality::ParameterChecking
+    include ::RazorRisk::Core::Diagnostics::Logger
+
+    module Authorisation_HeaderHelpers_Constants_
+
+        CIPHER_KEY_LENGTH       =   256
+        CIPHER_MODE             =   :CBC
+    end
+
+    # Constructs a Basic Authentication authorisation token from the given
+    # +username+, +password+, and, optionally, +domain+.
+    #
+    # === Signature
+    #
+    # * *Parameters:*
+    #   - +:username+ [ ::String ] - the username
+    #   - +:password+ [ ::String ] - the password. May be +nil+
+    #   - +:domain+ [ ::String ] - the domain. May be +nil+
+    #   - +:options+ [ ::Hash ] - options
+    #
+    # * *Options:*
+    #   - +:no_chomp+ [ boolean ] Prevents the result being chomped
+    #
+    # === Return
+    # A string of the form 'Basic <credentials-data>'. Note that the string
+    # will NOT contain a trailing new-line sequence unless the option
+    # +:no_chomp+ is specified
+    def Basic_from_credentials username, password, domain = nil, **options
+
+        trace ParamNames[ :username, :password, :domain, :options ], username, password, domain, options
+
+        check_parameter username, 'username', type: ::String
+
+        if (domain || '').empty?
+
+            credentials =   "#{username}:#{password}"
+        else
+
+            credentials =   "#{domain}\\#{username}:#{password}"
+        end
+
+        r   =   'Basic ' + [ credentials ].pack('m')
+
+        r   =   r.chomp unless options[:no_chomp]
+
+        r
+    end
+
+    # Returns a credentials array - [ username, password, domain ] - if
+    # present
+    #
+    # === Signature
+    #
+    # * *Parameters:*
+    #   - +auth+ [ ::String ] - the authorisation token, in the format
+    #   "Basic <credentials-data>"
+    #
+    # * *Options:*
+    #   - +:nil+ [Boolean] - causes +nil+ to be returned if not matched;
+    #     otherwise an empty +Array+ is returned
+    def credentials_from_Basic auth, **options
+
+        trace ParamNames[ :auth, :options ], auth, options
+
+        check_parameter auth, 'auth', type: ::String
+
+        if auth !~ /^Basic /i
+
+            log :failure, 'authorisation token is not Basic'
+        else
+
+            uid = $'.unpack('m')[0]
+
+            if uid !~ /^([^:]+):(.*)$/
+
+                log :failure, 'Basic authorisation token is not well-formed'
+            else
+
+                username    =   $1
+                password    =   $2
+                domain      =   nil
+
+                if username =~ /\\/
+
+                    domain, username = $`, $'
+                end
+
+                return [ username, password, domain ]
+            end
+        end
+
+        options[:nil] ? nil : []
+    end
+
+
+    # Constructs an Authentication-only authorisation token from the given
+    # +username+
+    #
+    # === Signature
+    #
+    # * *Parameters:*
+    #   - +:username+ [ ::String ] - the username
+    #   - +:options+ [ ::Hash ] - options
+    #
+    # * *Options:*
+    def AuthorisationOnly_from_credentials username, **options
+
+        trace ParamNames[ :username, :options ], username, options
+
+        check_parameter username, 'username', type: ::String
+
+        'RazorRisk.Cassini.AuthorisationOnly ' + [ username ].pack('m')
+    end
+
+    # Returns a credentials array containing only username
+    #
+    # === Signature
+    #
+    # * *Parameters:*
+    #   - +auth+ [ ::String ] - the authorisation token, in the format
+    #   "RazorRisk.Razor.AuthorisationOnly <credentials-data>"
+    #
+    # * *Options:*
+    #   - +:nil+ [Boolean] - causes +nil+ to be returned if not matched;
+    #     otherwise an empty +Array+ is returned
+    def credentials_from_AuthorisationOnly auth, **options
+
+        trace ParamNames[ :auth, :options ], auth, options
+
+        username = nil
+
+        if auth =~ /^RazorRisk\.(?:Cassini|Razor)\.Auth(?:ori[sz]ation)Only /i && !$'.empty?
+
+            username = $'.unpack('m')[0]
+
+            [ username, nil, nil ]
+        else
+
+            options[:nil] ? nil : []
+        end
+    end
+
+
+    # Constructs a JWT authorisation token for a user session.
+    #
+    # @param session_id [::String] The session ID.
+    # @param user_id [::String] The user ID.
+    # @param user_name [::String] The user's long name.
+    # @param jwt_algorithm [::String] the JWT algorithm
+    # @param jwt_secret [::String] the JWT secret
+    # @param options [::Hash] options
+    #
+    # @return [::String] The created JSON Web Token.
+    def JWT_from_credentials session_id, user_id, user_name, jwt_algorithm, jwt_secret, **options
+
+        trace(
+            ParamNames[ :session_id, :jwt_algorithm, :jwt_secret, :options ],
+            session_id, jwt_algorithm, jwt_secret, options
+        )
+
+        check_parameter session_id, 'session_id', type: ::String
+        check_parameter jwt_secret, 'jwt_secret', type: ::String
+
+        payload = {
+            'razorrisk.razor.user_id'    => user_id,
+            'razorrisk.razor.user_name'  => user_name,
+            'razorrisk.razor.session_id' => session_id,
+        }
+
+        JWT.encode payload, jwt_secret, jwt_algorithm
+    end
+
+
+    # Returns a credentials array from a JSON Web Token.
+    #
+    # * *Parameters:*
+    # @param auth [::String] The authorisation token, in the format "Bearer
+    #   <credentials-data>", where <credentials-data> is a JWT.
+    # @param jwt_secret [::String] The secret used for JWT encryption.
+    # @param options [::Hash] The options hash.
+    #
+    # @option options [Boolean] nil Causes +nil+ to be returned if not
+    #   matched; otherwise an empty +Array+ is returned.
+    #
+    # @return [Arrary<::String>] A credentials array, +[session_id]+, if
+    #   present.
+    def credentials_from_JWT auth, jwt_secret, **options
+
+        trace(
+            ParamNames[ :auth, :jwt_secret, :options ],
+            auth, jwt_secret, options
+        )
+
+        check_parameter auth, 'auth', type: ::String
+        check_parameter jwt_secret, 'jwt_secret', type: ::String
+
+        if auth !~ /^Bearer /i
+
+            log :failure, 'authorisation token is not Bearer'
+        else
+
+            jwt = $'.strip
+
+            payload, header = JWT.decode jwt, jwt_secret, true
+
+            if payload && header
+
+                session_id = payload['razorrisk.razor.session_id']
+                user_id    = payload['razorrisk.razor.user_id']
+                user_name  = payload['razorrisk.razor.user_name']
+
+                return [
+                    session_id,
+                    user_id,
+                    user_name
+                ] if session_id
+            end
+        end
+
+        options[:nil] ? nil : []
+    end
+end # module HeaderHelpers
+
+end # module Authorisation
+end # module Cassini
+end # module RazorRisk
+
+# ############################## end of file ############################# #
+
+