shamu 0.0.1 → 0.0.2

data/lib/shamu/rails/entity.rb

@@ -0,0 +1,168 @@
+module Shamu
+  module Rails
+
+    # Manages loading an entity as part of a controller action. See {.entity}
+    # for details.
+    module Entity
+      extend ActiveSupport::Concern
+
+      private
+
+        def fetch_entity( service, param )
+          service.find( params[ param ] )
+        end
+
+        def fetch_entities( service, param )
+          service.list( param ? params[ param ] : params )
+        end
+
+        def fetch_entity_request( service, entity, param_key )
+          action = params[ :action ].to_sym
+          return unless service.respond_to?( :request_for )
+          return unless request = service.request_for( action, entity )
+
+          param_key ||= entity.model_name.param_key
+
+          strong_param = :"#{ param_key }_params"
+          if respond_to?( strong_param, true )
+            request.assign_attributes( send( strong_param ) )
+          else
+            request.assign_attributes( params[ param_key ] )
+          end
+
+          service.authorize!( action, entity, request ) if service.respond_to?( :authorize! )
+          request
+        end
+
+        def load_entity( method:, list_method:, action: nil, only: nil, except: nil )
+          action ||= params[ :action ].to_sym
+          return unless matching_entity_action?( action, only: only, except: except )
+
+          send list_action?( action ) ? list_method : method
+        end
+
+        def matching_entity_action?( action, only:, except: )
+          return if only.present? && !only.include?( action )
+          return if except.present? && except.include?( action )
+          true
+        end
+
+        def list_action?( action )
+          action == :index
+        end
+
+      class_methods do
+
+        # Declare an entity dependency to be resolved before the requested
+        # controller action. Shamu will attempt to load an entity through the
+        # service and make it available to the controller as an attribute and
+        # a helper method.
+        #
+        # Adds a method named after the entity excluding the namespace and
+        # "Entity" suffix (Users::UserEntity => #user). It also makes an
+        # entity_request method available for mutating actions such as new,
+        # create, update, edit, etc.
+        #
+        # ```
+        # class UsersController < ApplicationController
+        #   service :users_service, Users::UsersService
+        #   entity Users::UserEntity
+        #
+        #   def show
+        #     render json: { name: user.name, id: user.id }
+        #   end
+        #
+        #   def update
+        #     result = users_service.update( user_request )
+        #     respond_with result
+        #   end
+        # end
+        # ```
+        #
+        # @param [Class] entity_class an {Entities::Entity} class to be loaded.
+        # @param [Symbol] through the name of the service to fetch the entity
+        #     from. If not set, guesses the name of the service from the entity
+        #     class.
+        # @param [Symbol] as the name of the method to expose the entity
+        #     through.
+        # @param [Symbol] list the name of the method to expose the list of
+        #     entities for index actions.
+        # @param [Array<Symbol>] only load the entity only for the given
+        #     actions.
+        # @param [Array<Symbol>] except load the entity except for the given
+        #     actions.
+        # @param [Symbol] param the request param that holds the id of the
+        #     entity.
+        # @param [Symbol] list_param request param that hols list scope params.
+        # @param [Symbol] param_key request param that holds the attributes used
+        #     to populate the service change request.
+        # @param [Symbol] action override the default action detection. For
+        #     example always use :show for a secondary or root entity that is
+        #     not being modified in an :update request.
+        def entity( entity_class, through: nil, as: nil, list: nil, only: nil, except: nil, param: :id, list_param: nil, action: nil, param_key: nil ) # rubocop:disable Metrics/LineLength
+          as      ||= entity_as_name( entity_class )
+          through ||= :"#{ as }_service"
+          list    ||= as.to_s.pluralize.to_sym
+
+          define_entity_method( as, through, param )
+          define_entities_method( list, through, list_param )
+          define_entity_request_method( as, through, param_key )
+
+          before_action do
+            load_entity( method: as,
+                         list_method: list,
+                         action: action,
+                         only: only && Array( only ),
+                         except: except && Array( except ) )
+          end
+        end
+
+        private
+
+          def entity_as_name( entity_class )
+            entity_class.model_name.element
+          end
+
+          def define_entity_method( as, through, param )
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              private
+
+              def #{ as }                                                                    # def entity
+                return @#{ as } if defined? @#{ as }                                         #   return @entity if defined? @entity
+                @#{ as } = fetch_entity( #{ through }, :#{ param } )                         #   @entity = fetch_entity( entity_service, :id )
+              end                                                                            # end
+
+              helper_method :#{ as }
+            RUBY
+          end
+
+          def define_entities_method( as, through, param )
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              private
+
+              def #{ as }                                                                     # def entities
+                return @#{ as } if defined? @#{ as }                                          #   return @entities if defined? @entities
+                @#{ as } = fetch_entities( #{ through }, #{ param ? ":#{ param }" : 'nil' } ) #   @entities = fetch_entities( entity_service, nil )
+              end                                                                             # end
+
+              helper_method :#{ as }
+            RUBY
+          end
+
+          def define_entity_request_method( as, through, param )
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              private
+
+              def #{ as }_request                                                              # def entity_request
+                return @#{ as }_request if defined? @#{ as }_request                           #   return @entity_request if defined? @entity_request
+                @#{ as }_request = fetch_entity_request( #{ through }, #{ as }, :#{ as } )     #   @entity_request = fetch_entity_request( entity_service, entity, :entity )
+              end                                                                              # end
+
+              helper_method :#{ as }_request
+            RUBY
+          end
+
+      end
+    end
+  end
+end

data/lib/shamu/rails/features.rb

@@ -0,0 +1,13 @@
+module Shamu
+  module Rails
+
+    # Add support for testing for feature toggles to controllers and views.
+    module Features
+      extend ActiveSupport::Concern
+
+      included do
+        include Shamu::Features::Support
+      end
+    end
+  end
+end

data/lib/shamu/rails/railtie.rb

@@ -0,0 +1,30 @@
+require "shamu/rack"
+
+module Shamu
+  module Rails
+
+    # Integrate Shamu with rails.
+    class Railtie < ::Rails::Railtie
+
+      rake_tasks do
+        rake_path = File.expand_path( "../../tasks/*.rake" )
+        Dir[ rake_path ].each { |f| load f }
+      end
+
+      initializer "shamu.configure" do
+        if defined? ::ActionController
+          ::ActionController::Base.send :include, Shamu::Rails::Controller
+          ::ActionController::Base.send :include, Shamu::Rails::Entity
+          ::ActionController::Base.send :include, Shamu::Rails::Features
+        end
+      end
+
+      initializer "shamu.insert_middleware" do |app|
+        app.config.middleware.use "Scorpion::Rack::Middleware"
+        app.config.middleware.use "Shamu::Rack::CookiesMiddleware"
+        app.config.middleware.use "Shamu::Rack::QueryParamsMiddleware"
+      end
+
+    end
+  end
+end

data/lib/shamu/rails.rb

@@ -0,0 +1,10 @@
+module Shamu
+
+  # Rails integration.
+  module Rails
+    require "shamu/rails/entity"
+    require "shamu/rails/controller"
+    require "shamu/rails/features"
+    require "shamu/rails/railtie"
+  end
+end

data/lib/shamu/rspec/matchers.rb

@@ -0,0 +1,44 @@
+
+RSpec::Matchers.define :be_permitted_to do |*args|
+
+  def supports_block_expectations?
+    true
+  end
+
+  failure_message do |actual|
+    "expected that #{ actual.class.name } would be permitted to #{ expected.first } #{ expected.second }"
+  end
+  match do |policy|
+    policy.permit?( *args )
+  end
+end
+
+RSpec::Matchers.define :maybe_be_permitted_to do |*args|
+
+  def supports_block_expectations?
+    true
+  end
+
+  failure_message do |actual|
+    "expected that #{ actual.class.name } might be permitted to #{ expected.first } #{ expected.second }"
+  end
+
+  match do |policy|
+    policy.permit?( *args ) == :maybe
+  end
+end
+
+RSpec::Matchers.define :absolutely_be_permitted_to do |*args|
+
+  def supports_block_expectations?
+    true
+  end
+
+  failure_message do |actual|
+    "expected that #{ actual.class.name } would absolutely be permitted to #{ expected.first } #{ expected.second }"
+  end
+
+  match do |policy|
+    policy.permit?( *args ) == :yes
+  end
+end

data/lib/shamu/rspec.rb

@@ -0,0 +1 @@
+require "shamu/rspec/matchers"

data/lib/shamu/security/active_record_policy.rb

@@ -0,0 +1,106 @@
+module Shamu
+  module Security
+
+    # Extends the standard {Policy} class to add {ActiveRecord::Relation}
+    # refinements based on granted policies.
+    #
+    # @example
+    #   class UserPolicy < Shamu::Security::ActiveRecordPolicy
+    #     private
+    #
+    #       def permissions
+    #         permit :read, UserEntity do |user|
+    #           user.public?
+    #         end
+    #
+    #         refine :read, Models::User do |users, additional_context|
+    #           users.where( public: true )
+    #         end
+    #       end
+    #
+    #   end
+    #
+    #   class UsersService < Shamu::Services::Service
+    #     include Shamu::Security::Support
+    #
+    #     def list
+    #       entity_list policy.refine_relation( :list, Model::User.all ) do |record|
+    #         scorpion.fetch UserEntity, { record: record }, {}
+    #       end
+    #     end
+    #
+    #     private
+    #
+    #       def policy_class
+    #         UserPolicy
+    #       end
+    #   end
+    class ActiveRecordPolicy < Policy
+
+      # Refine an {ActiveRecord::Relation} to select only those records
+      # permitted for the given `action`.
+      #
+      # @param [Symbol] action to perform on the {Entities::Entity} that will be
+      #     projected from the records.
+      # @param [ActiveRecord::Relation] relation to refine.
+      # @param [Object] additional_context that the {#refine} block may consider
+      #     when applying the refinement.
+      # @return [ActiveRecord::Relation] the refined relation.
+      def refine_relation( action, relation, additional_context = nil )
+        refined = false
+
+        refinements.each do |refinement|
+          if refinement.match?( action, relation )
+            refined  = true
+            relation = refinement.apply( relation, additional_context ) || relation
+          end
+        end
+
+        refined ? relation : relation.none
+      end
+
+      private
+
+        # ============================================================================
+        # @!group Dependencies
+        #
+
+        # @!visibility public
+        #
+        # Declare a refinement that should be applied to an
+        # {ActiveRecord::Relation} for the given actions. {#refine_relation}
+        # will yield the relation to any matching refinement to reduce the scope
+        # of available records available for projection.
+        #
+        # @example
+        #   def permissions
+        #     permit :read, UserEntity do |user|
+        #       user.public?
+        #     end
+        #     refine :read, Models::User do |users, additional_context|
+        #       users.where( public: true )
+        #     end
+        #   end
+        #
+        # @param [Array<Symbol>] actions that should be refined.
+        # @param [Class] model_class the {ActiveRecord::Base} class to refine.
+        # @yield (relation, additional_context)
+        # @yieldparam [ActiveRecord::Relation] relation to refine.
+        # @yieldparam [Object] additional_context offered to {#refine_relation}.
+        # @yieldreturn [ActiveRecord::Relation,nil] the refined relation, or nil
+        #     if no refinement should be applied.
+        # @return [void]
+        def refine( *actions, model_class, &block )
+          refinements << PolicyRefinement.new( expand_aliases( actions ), model_class, block )
+        end
+
+        #
+        # @!endgroup Dependencies
+
+        def refinements
+          @refinements ||= []
+        end
+
+    end
+  end
+end

data/lib/shamu/security/error.rb

@@ -0,0 +1,65 @@
+require "i18n"
+
+module Shamu
+  module Security
+
+    # A generic error class for problems with shamu services.
+    class Error < Shamu::Error
+      private
+
+        def translation_scope
+          super.dup.insert( 1, :security )
+        end
+
+    end
+
+    # The requested action was not permitted on the resource.
+    class AccessDeniedError < Error
+
+      # ============================================================================
+      # @!group Attributes
+      #
+
+      # @return [Symbol] the requested action that was denied.
+      attr_reader :action
+
+      # @return [Object] the resource the {#action} was to be performed on.
+      attr_reader :resource
+
+      # @return [Principal] the security {Principal} in use at the time of the
+      #     policy violation.
+      attr_reader :principal
+
+      # @return [Object] additional principal provided to the policy authorization
+      #     method.
+      attr_reader :additional_context
+
+      #
+      # @!endgroup Attributes
+
+      def initialize( message = :access_denied, action: nil, resource: nil, principal: nil, additional_context: nil )
+        @action             = action
+        @resource           = resource
+        @principal          = principal
+        @additional_context = additional_context
+
+        super translate( :access_denied, action: action, resource: resource )
+      end
+    end
+
+    # Security has been included but has not been completely set up.
+    class IncompleteSetupError < Error
+      def initialize( message = :incomplete_setup )
+        super
+      end
+    end
+
+    # A policy check was performed on an ActiveRecord resource
+    class NoActiveRecordPolicyChecksError < Error
+      def initialize( message = :no_actiev_record_policy_checks )
+        super
+      end
+    end
+
+  end
+end

data/lib/shamu/security/hashed_value.rb

@@ -0,0 +1,71 @@
+require "openssl"
+
+module Shamu
+  module Security
+
+    # Adds support for hashing and verifying a string value.
+    #
+    # ```ruby
+    # class Codec
+    #   include Shamu::Security::HashedValue
+    #
+    #   def initialize( private_key = Shamu::Security.private_key )
+    #     @private_key = private_key
+    #   end
+    #
+    #   def store( value )
+    #     hash_value( value )
+    #   end
+    #
+    #   def restore( hashed )
+    #     verify_hash( hashed )
+    #   end
+    # end
+    #
+    # codec = Codec.new
+    # signed = codec.store "example"  # => "0123456789abcdef0123456789abcdef012345678;example"
+    # codec.restore signed            # => "example"
+    # codec.restore "example"         # => nil
+    # ```
+    module HashedValue
+
+      private
+
+        # @!visiblity public
+        # @return [String] the private key used to sign the hashes.
+        attr_reader :private_key
+
+        # @!visibility public
+        #
+        # @param [String] string to hash.
+        # @return [String] packed string with hash and original value.
+        def hash_value( string )
+          return nil unless string
+          "#{ hash_digest( string ) }$#{ string }"
+        end
+
+        def hash_digest( string )
+          alg = OpenSSL::Digest::SHA1.new
+          OpenSSL::HMAC.hexdigest( alg, private_key, string )
+        end
+
+        # @!visiblity public
+        #
+        # Verify that the hashed value has not been modified.
+        #
+        # @param [String] hashed value returned from {#hash_value}.
+        # @return [String] the original value.
+        def verify_hash( hashed )
+          return unless hashed
+          return if hashed.length < 41
+
+          mac     = hashed[ 0...40 ]
+          toggles = hashed[ 41..-1 ]
+
+          return unless hash_digest( toggles ) == mac
+
+          toggles
+        end
+    end
+  end
+end

data/lib/shamu/security/no_policy.rb

@@ -0,0 +1,15 @@
+module Shamu
+  module Security
+
+    # Used in specs and service to service delegated requests to effectively
+    # offer no policy and permit all actions.
+    class NoPolicy
+
+      # (see Policy#permit?)
+      def permit?( * )
+        :yes
+      end
+
+    end
+  end
+end