shamu 0.0.1 → 0.0.2

data/lib/shamu/security/policy.rb

@@ -0,0 +1,289 @@
+require "shamu/security/roles"
+
+module Shamu
+  module Security
+
+    # ...
+    #
+    # @example
+    #   class UserPolicy < Shamu::Security::Policy
+    #
+    #     role :admin, inherits: :manager
+    #     role :manager
+    #     role :user
+    #
+    #     private
+    #
+    #       def permissions
+    #         alias_action :email, to: :contact
+    #
+    #         permit :contact, UserEntity if in_role?( :manager )
+    #         permit :email, UserEntity do |user|
+    #           user.public_profile?
+    #         end
+    #       end
+    #   end
+    #
+    #   principal = Shamu::Security::Principal.new( user_id: user.id )
+    #   policy = UserPolicy.new(
+    #     principal: principal,
+    #     roles: roles_service.roles_for( principal )
+    #     )
+    #
+    #   if policy.permit? :contact, user
+    #     mail_to user
+    #   end
+    class Policy
+      include Security::Roles
+
+      # ============================================================================
+      # @!group Dependencies
+      #
+
+      # @!attribute
+      # @return [Principal] principal holding user identity and access credentials.
+        attr_reader :principal
+
+      # @!attribute
+      # @return [Array<Roles>] roles that have been granted to the {#principal}.
+        attr_reader :roles
+      #
+      # @!endgroup Dependencies
+
+      def initialize( principal: nil, roles: nil )
+        @principal = principal || Principal.new
+        @roles     = roles || []
+      end
+
+
+      # Authorize the given `action` on the given resource. If it is not
+      # {#permit? permitted} then an exception is raised.
+      #
+      # @param (see #permit?)
+      # @return [resource]
+      # @raise [AccessDeniedError] if not permitted.
+      def authorize!( action, resource, additional_context = nil )
+        return resource if permit?( action, resource, additional_context ) == :yes
+
+        fail Security::AccessDeniedError,
+             action: action,
+             resource: resource,
+             additional_context: additional_context,
+             principal: principal
+      end
+
+      # Determines if the given `action` may be performed on the given
+      # `resource`.
+      #
+      # @param [Symbol] action to perform.
+      # @param [Object] resource the resource the action will be performed on.
+      # @param [Object] additional_context that the policy may consider.
+      # @return [:yes, :maybe, false] a truthy value if permitted, otherwise
+      #     false. The truthy value depends on the certainty of the policy. A
+      #     value of `:yes` or `true` indicates the action is always permitted.
+      #     A value of `:maybe` indicates the action is permitted but the user
+      #     may need to present additional credentials such as logging on this
+      #     session or entering a TFA code.
+      def permit?( action, resource, additional_context = nil )
+        fail_on_active_record_check( resource )
+
+        rules.each do |rule|
+          next unless rule.match?( action, resource, additional_context )
+
+          return rule.result
+        end
+
+        false
+      end
+
+      private
+
+        # The rules that have been defined.
+        def rules
+          @rules ||= begin
+            @rules = []
+            permissions
+            @rules
+          end
+        end
+
+        # Mapping of action names to aliases.
+        def aliases
+          @aliases ||= {}
+        end
+
+        # @!visibility public
+        #
+        # @param [Array<Symbol>] roles to check.
+        # @return [Boolean] true if the {#principal} has been granted one of the
+        #     given roles.
+        def in_role?( *roles )
+          ( principal_roles & roles ).any?
+        end
+
+        def principal_roles
+          @principal_roles ||= begin
+            expanded = self.class.expand_roles( *roles )
+            expanded << :user if principal.user_id && self.class.role_defined?( :user )
+            expanded
+          end
+        end
+
+        # ============================================================================
+        # @!group DSL
+        #
+
+        # @!visibility public
+        #
+        # Hook to be overridden by a derived class to define the set of rules
+        # that {#permit?} should consider when evaluating the {#principal}'s
+        # permissions on a resource.
+        #
+        # Rules defined in the permissions block are evaluated in reverse order
+        # such that the last matching {#permit} or {#deny} will determine the
+        # permission.
+        #
+        # If no rules match, the permission is denied.
+        #
+        # @example
+        #   def permissions
+        #     permit :read, UserEntity
+        #
+        #     deny :read, UserEntity do |user|
+        #       user.protected_account? && !in_role( :admin )
+        #     end
+        #   end
+        #
+        # @return [void]
+        def permissions
+          fail IncompleteSetupError, "Permissions have not been defined. Add a private `permissions` method to #{ self.class.name }" # rubocop:disable Metrics/LineLength
+        end
+
+        # @!visibility public
+        #
+        # Permit one or more `actions` to be performed on a given `resource`.
+        #
+        # When a block is provided the policy will yield to the block to allow
+        # for more complex or context aware policy checks. The block is not
+        # called if the resource offered to {#permit?} is a Class or Module.
+        #
+        # @example
+        #   permit :read, UserEntity
+        #   permit :show, :dashboard
+        #   permit :update, UserEntity do |user|
+        #     user.id == principal.user_id
+        #   end
+        #   permit :destroy, UserEntity do |user, additional_context|
+        #     in_role?( :admin ) && additional_context[:custom_data] == :safe
+        #   end
+        #
+        # @param [Array<Symbol>] actions to be permitted.
+        # @param [Object] resource to perform the action on or the Class of
+        #     instances to permit the action on.
+        # @yield ( resource, additional_context )
+        # @yieldparam [Object] resource instance or Class offered to {#permit?}
+        #     that the requested action is to be performed on.
+        # @yieldparam [Object] additional_context offered to {#permit?}.
+        # @yieldreturn [:yes, :maybe, false] see {#permit?}.
+        # @return [void]
+        def permit( *actions, resource, &block )
+          result = @when_elevated ? :maybe : :yes
+
+          add_rule( actions, resource, result, &block )
+        end
+
+        # @!visibility public
+        #
+        # Explicitly deny an action previously granted with {#permit}.
+        #
+        # @param (see #permit)
+        # @return [void]
+        # @yield (see #permit)
+        # @yieldparam (see #permit)
+        # @yieldreturn [Boolean] true to deny the action.
+        def deny( *actions, resource, &block )
+          add_rule( actions, resource, false, &block )
+        end
+
+        # @!visibility public
+        #
+        # Only {#authorize!} the permissions defined in the given block when the
+        # {#principal} has elevated this session by providing their credentials.
+        #
+        # Permissions defined in the block will yield a `:maybe` result when
+        # queried via {#permit?} and will raise an {AccessDeniedError} when
+        # an {#authorize!} check is enforced.
+        #
+        # This allows you to enable/disable UX in response to what a user should
+        # be capable of doing but wait to actually allow it until they have
+        # offered their credentials.
+        #
+        # @return [void]
+        def when_elevated( &block )
+          current = @when_elevated
+          @when_elevated = true
+          yield
+          @when_elevated = current
+        end
+
+        # @!visibility public
+        #
+        # Add an action alias so that granting the alias will result in permits
+        # for any of the listed actions.
+        #
+        # @example
+        #  alias_action :show, :list, to: :read
+        #  permit :read, :stuff
+        #
+        #  permit?( :show, :stuff )  # => :yes
+        #  permit?( :list, :stuff )  # => :yes
+        #  permit?( :read, :stuff )  # => :yes
+        #  permit?( :write, :stuff ) # => false
+        #
+        # @param [Array<Symbol>] actions to alias.
+        # @param [Symbol] to the action that should permit all the listed aliases.
+        # @return [void]
+        def alias_action( *actions, to: fail ) # bug in rubocop chokes on trailing required keyword
+          aliases[to] ||= []
+          aliases[to] |= actions
+        end
+
+        #
+        # @!endgroup DSL
+
+        def add_rule( actions, resource, result, &block )
+          rules.unshift PolicyRule.new( expand_aliases( actions ), resource, result, block )
+        end
+
+        def expand_aliases( actions )
+          expanded = actions.dup
+          actions.each do |action|
+            expand_alias_into( action, expanded )
+          end
+
+          expanded
+        end
+
+        def expand_alias_into( candidate, expanded )
+          return unless mapped = aliases[candidate]
+
+          mapped.each do |action|
+            next if expanded.include? action
+
+            expanded << action
+            expand_alias_into( action, expanded )
+          end
+        end
+
+        def fail_on_active_record_check( resource )
+          return unless resource
+          return unless defined? ActiveRecord
+
+          if resource.is_a?( ActiveRecord::Base ) || ( resource.is_a?( Class ) && resource < ActiveRecord::Base )
+            fail NoActiveRecordPolicyChecksError
+          end
+        end
+
+    end
+  end
+end

data/lib/shamu/security/policy_refinement.rb

@@ -0,0 +1,50 @@
+module Shamu
+  module Security
+
+    # Defines how an {ActiveRecord::Relation} is refined for an
+    # {ActiveRecordPolicy}.
+    class PolicyRefinement
+
+      def initialize( actions, model_class, block )
+        @actions     = actions
+        @model_class = model_class
+        @block       = block
+      end
+
+      # Determines if the refinement matches the request action permission on
+      # the given relation.
+      #
+      # @param [Symbol] action to be performed on entities projected from the
+      #     `relation`.
+      # @param [ActiveRecord::Relation] relation to refine.
+      # @param [Object] additional context offered to {Policy#permit?}.
+      #
+      # @return [Boolean] true if the rule is a match.
+      def match?( action, relation, additional_context )
+        return false unless actions.include? action
+        return false unless model_class_match?( relation )
+
+        true
+      end
+
+      # Apply the refinement to the relation.
+      #
+      # @param [ActiveRecord::Relation] relation to refine
+      # @return [ActiveRecord::Relation]
+      def apply( relation, additional_context )
+        ( block && block.call( relation, additional_context ) ) || relation
+      end
+
+      private
+
+        attr_reader :actions
+        attr_reader :model_class
+        attr_reader :block
+
+        def model_class_match?( candidate )
+          model_class <= candidate.klass
+        end
+
+    end
+  end
+end

data/lib/shamu/security/policy_rule.rb

@@ -0,0 +1,59 @@
+module Shamu
+  module Security
+
+    # A rule capturing the permitted actions and resources for {Policy}
+    # permissions.
+    class PolicyRule
+
+      # ============================================================================
+      # @!group Attributes
+      #
+
+      # @!attribute
+      # @return [Object] the value to return as the result of a {Policy#permit?}
+      #     call if the rule matches the request.
+        attr_reader :result
+
+      #
+      # @!endgroup Attributes
+
+      def initialize( actions, resource, result, block )
+        @actions  = actions
+        @resource = resource
+        @result   = result
+        @block    = block
+      end
+
+      # Determines if the rule matches the request action permission on the
+      # given resource.
+      #
+      # @param [Symbol] action to be performed.
+      # @param [Object] resource the action will be performed on.
+      # @param [Object] additional context offered to {Policy#permit?}.
+      #
+      # @return [Boolean] true if the rule is a match.
+      def match?( action, resource, additional_context )
+        return false unless actions.include? action
+        return false unless resource_match?( resource )
+
+        if block && !resource.is_a?( Module )
+          block.call( resource, additional_context )
+        else
+          true
+        end
+      end
+
+      private
+
+        attr_reader :actions
+        attr_reader :resource
+        attr_reader :block
+
+        def resource_match?( candidate )
+          return true if resource == candidate
+          return true if resource.is_a?( Module ) && candidate.is_a?( resource )
+        end
+
+    end
+  end
+end

data/lib/shamu/security/principal.rb

@@ -0,0 +1,72 @@
+module Shamu
+  module Security
+
+    # ...
+    class Principal
+
+      # ============================================================================
+      # @!group Attributes
+      #
+
+      # @!attribute
+      # @return [Object] id of the currently authenticated user. May be cached,
+      #     for example bu via persistent cookie. See {#elevated}.
+        attr_reader :user_id
+
+      # @!attribute
+      # @return [Principal] the parent principal when a user or service is
+      #     impersonating another user.
+        attr_reader :parent_principal
+
+      # @!attribute
+      # @return [String] the IP address of the remote user.
+        attr_reader :remote_ip
+
+      # @!attribute
+      # @return [Boolean] true if the user has elevated this session by
+      #     providing their credentials.
+        attr_reader :elevated
+        alias_method :elevated?, :elevated
+
+      #
+      # @!endgroup Attributes
+
+      def initialize( user_id: nil, parent_principal: nil, remote_ip: nil, elevated: false )
+        @user_id          = user_id
+        @parent_principal = parent_principal
+        @remote_ip        = remote_ip
+        @elevated         = elevated
+      end
+
+      # @return [Array<Object>] all of the user ids in the security principal
+      #  chain, starting from the root.
+      def user_id_chain
+        @user_ids ||= begin
+          user_ids = []
+          principal = self
+          while principal
+            user_ids << principal.user_id
+            principal = principal.parent_principal
+          end
+
+          user_ids.reverse
+        end
+      end
+
+      # @return [Boolean] true if the [#user_id] is being impersonated.
+      def impersonated?
+        !!parent_principal
+      end
+
+      # Create a new impersonation {Principal}, cloning relevant principal to the
+      # new instance.
+      #
+      # @param [Object] user_id of the user to impersonate.
+      # @return [Principal] the new principal.
+      def impersonate( user_id )
+        self.class.new( user_id: user_id, parent_principal: self, remote_ip: remote_ip, elevated: elevated )
+      end
+
+    end
+  end
+end

data/lib/shamu/security/roles.rb

@@ -0,0 +1,62 @@
+module Shamu
+  module Security
+
+    # Mixin for {Policy} and {Support} classes to define security roles
+    # including inheritance.
+    module Roles
+      extend ActiveSupport::Concern
+
+      class_methods do
+
+        # @return [Hash] the named roles defined on the class.
+        def roles
+          @roles ||= {}
+        end
+
+        # Define a named role.
+        #
+        # @param [Symbol] name of the role.
+        # @param [Array<Symbol>] inherits additional roles that are
+        #     automatically inherited when the named role is granted.
+        # @return [void]
+        def role( name, inherits: nil )
+          roles[ name.to_sym ] = { inherits: Array( inherits ) }
+        end
+
+        # Expand the given roles to include the roles that they have inherited.
+        # @param [Array<Symbol>] roles
+        # @return [Array<Symbol>] the expanded roles.
+        def expand_roles( *roles )
+          expand_roles_into( roles, [] )
+        end
+
+        # @param [Symbol] the role to check.
+        # @return [Boolean] true if the role has been defined.
+        def role_defined?( role )
+          roles.key?( role.to_sym )
+        end
+
+        private
+
+          def expand_roles_into( roles, expanded )
+            roles.each do |name|
+              name = name.to_sym
+
+              next unless role = self.roles[ name ]
+              expanded << name
+
+              role[ :inherits ].each do |inherited|
+                next if expanded.include?( inherited )
+
+                expanded << inherited
+                expand_roles_into( [ inherited ], expanded )
+              end
+            end
+
+            expanded
+          end
+
+      end
+    end
+  end
+end

data/lib/shamu/security/roles_service.rb

@@ -0,0 +1,30 @@
+module Shamu
+  module Security
+
+    # Used to determine the roles that the current {Principal} should be given
+    # on a {Services::Service}.
+    module RolesService
+
+      # @!visibility private
+      def self.create( scorpion, * )
+        scorpion.new EmptyRolesService
+      end
+
+      # @param [Principal] principal of the currently logged in user.
+      # @return [Array<Symbol>] the roles granted to the principal.
+      def roles_for( principal )
+        []
+      end
+
+      # Default {RolesService} always returns an empty set.
+      class EmptyRolesService
+        include RolesService
+
+        # (see RolesService#roles_for)
+        def roles_for( principal )
+          []
+        end
+      end
+    end
+  end
+end

data/lib/shamu/security/support.rb

@@ -0,0 +1,83 @@
+module Shamu
+  module Security
+
+    # Adds support for authorizing and querying security {Policy} to a
+    # {Services::Service}.
+    module Support
+      extend ActiveSupport::Concern
+
+      # ============================================================================
+      # @!group Dependencies
+      #
+
+      # @!attribute security_principal
+      # @return [Security::Principal] the principal offered to the service for
+      #     policy resolution.
+
+      # @!attribute roles_service
+      # @return [Security::RolesService] a roles service to retrieve the roles
+      #     granted to the {#security_principal}.
+
+      #
+      # @!endgroup Dependencies
+
+      included do
+        attr_dependency :security_principal, Security::Principal unless method_defined? :security_principal
+        attr_dependency :roles_service, Security::RolesService unless method_defined? :roles_service
+      end
+
+      # @return [Policy] the security {Policy} for the service.
+      def policy
+        @policy ||= _policy_class.new(
+          principal: security_principal,
+          roles: roles_service.roles_for( security_principal )
+        )
+      end
+
+      # @!method authorize!( action, resource, additional_context = nil )
+      # @see Security::Policy#authorize!
+      # @return [resource]
+
+      # @!method permit?( action, resource, additional_context = nil )
+      # @see Policy#permit?
+      # @return [:yes, :maybe, false]
+
+      delegate :authorize!, :permit?, to: :policy
+
+      private
+
+        def _policy_class
+          if service_policy_delegation?
+            delegate_policy_class
+          else
+            policy_class
+          end
+        end
+
+        # @!visibility public
+        #
+        # Override to declare the policy class to use for the service.
+        #
+        # @return [Class] a {Policy} class used to authorize actions.
+        def policy_class
+          fail Security::IncompleteSetupError, "No policy class defined. Override #policy_class in #{ self.class.name } to declare policy." # rubocop:disable Metrics/LineLength
+        end
+
+        # @!visibility public
+        #
+        # @return [Class] a {Policy} class used when
+        #     {#service_policy_delegation?}  is true.
+        def delegate_policy_class
+          NoPolicy
+        end
+
+        # @!visibility public
+        #
+        # @return [Boolean] true if the service has been asked to delegate
+        #     policy checks to the upstream service and
+        def service_policy_delegation?
+        end
+
+    end
+  end
+end

data/lib/shamu/security.rb

@@ -0,0 +1,43 @@
+module Shamu
+  # {include:file:lib/shamu/security/README.md}
+  module Security
+    require "shamu/security/error"
+    require "shamu/security/principal"
+    require "shamu/security/policy"
+    require "shamu/security/policy_rule"
+    require "shamu/security/no_policy"
+    require "shamu/security/support"
+    require "shamu/security/roles"
+    require "shamu/security/roles_service"
+    require "shamu/security/hashed_value"
+
+    # See {.private_key}
+    ENV_PRIVATE_KEY = "SHAMU_PRIVATE_KEY".freeze
+
+    # @!attribute
+    #
+    # A strong key used to authenticate (not encrypt) input from untrusted
+    # sources (such as cookies, headers, etc).
+    #
+    # If the key has not been {#private_key= set then shamu will look for an
+    # environment variable named SHAMU_PRIVATE_KEY.
+    #
+    # ## To generate a strong key
+    #
+    # ```
+    # # 1024-bit private key
+    # key = SecureRandom.base64( 128 )
+    # ```
+    # @return [String]
+    def self.private_key
+      @private_key ||= ENV[ ENV_PRIVATE_KEY ] || fail( "No private key configured. Set Shamu::Security.private_key or add an the #{ ENV_PRIVATE_KEY } environment variable to the host." ) # rubocop:disable Metrics/LineLength
+    end
+
+    # @param [String] key to use.
+    # @return [String]
+    def self.private_key=( key )
+      @private_key = key && Base64.decode64( key )
+    end
+
+  end
+end

data/lib/shamu/services/README.md

@@ -0,0 +1,2 @@
+Services expose a clearly defined interface for managing {Entities::Entity} objects and
+external resources.