heimdallr 0.0.1 → 0.0.2

data/lib/heimdallr/model.rb

@@ -1,34 +1,65 @@
 module Heimdallr
+  # Heimdallr is attached to your models by including the module and defining the
+  # restrictions in your classes.
+  #
+  #     class Article < ActiveRecord::Base
+  #       include Heimdallr::Model
+  #
+  #       restrict do |context|
+  #         # ...
+  #       end
+  #     end
+  #
+  # @todo Improve description
   module Model
     extend ActiveSupport::Concern
 
+    # Class methods for {Heimdallr::Model}. See also +ActiveSupport::Concern+.
     module ClassMethods
-      def restrict(&block)
-        @restrictions = Evaluator.new(self, &block)
-      end
-
-      def restricted?
-        !@restrictions.nil?
+      # @overload restrict
+      #   Define restrictions for a model with a DSL. See {Model} overview
+      #   for DSL documentation.
+      #
+      #   @yield A passed block is executed in the context of a new {Evaluator}.
+      #
+      # @overload restrict(context, action=:view)
+      #   Return a secure collection object for the current scope.
+      #
+      #   @param [Object] context security context
+      #   @param [Symbol] action  kind of actions which will be performed
+      #   @return [Proxy::Collection]
+      def restrict(context=nil, &block)
+        if block
+          @restrictions = Evaluator.new(self, &block)
+        else
+          Proxy::Collection.new(context, restrictions(context).request_scope)
+        end
       end
 
+      # Evaluate the restrictions for a given +context+.
+      #
+      # @return [Evaluator]
       def restrictions(context)
         @restrictions.evaluate(context)
       end
     end
 
-    module InstanceMethods
-      def to_proxy(context, action)
-        if self.class.restricted?
-          Proxy.new(context, action, self)
-        else
-          self
-        end
-      end
+    # Return a secure proxy object for this record.
+    #
+    # @return [Record::Proxy]
+    def restrict(context, action)
+      Record::Proxy.new(context, self)
+    end
 
-      def validate_action(context, action)
-        if self.class.restricted?
-          self.class.restrictions(context).validate(action, self)
-        end
+    # @api private
+    #
+    # An internal attribute to store the Heimdallr security validators for
+    # the context in which this object is currently being saved.
+    attr_accessor :heimdallr_validators
+
+    def self.included(klass)
+      klass.const_eval do
+        validates_with Heimdallr::Validator
       end
     end
   end

data/lib/heimdallr/proxy/collection.rb

@@ -0,0 +1,28 @@
+module Heimdallr
+  # A security-aware proxy for +ActiveRecord+ scopes. This class validates all the
+  # method calls and either forwards them to the encapsulated scope or raises
+  # an exception.
+  class Proxy::Collection
+    # Create a collection proxy.
+    # @param context security context
+    # @param object  proxified scope
+    def initialize(context, scope)
+      @context, @scope = context, scope
+
+      @restrictions = @object.class.restrictions(context)
+    end
+
+    # Collections cannot be restricted twice.
+    #
+    # @raise [RuntimeError]
+    def restrict(context)
+      raise RuntimeError, "Collections cannot be restricted twice"
+    end
+
+    # Dummy method_missing.
+    # @todo Write some actual dispatching logic.
+    def method_missing(method, *args, &block)
+      @scope.send method, *args
+    end
+  end
+end

data/lib/heimdallr/proxy/record.rb

@@ -0,0 +1,236 @@
+module Heimdallr
+  # A security-aware proxy for individual records. This class validates all the
+  # method calls and either forwards them to the encapsulated object or raises
+  # an exception.
+  #
+  # The #touch method call isn't considered a security threat and as such, it is
+  # forwarded to the underlying object directly.
+  class Proxy::Record
+    # Create a record proxy.
+    # @param context security context
+    # @param object  proxified record
+    def initialize(context, record)
+      @context, @record = context, record
+
+      @restrictions = @record.class.restrictions(context)
+    end
+
+    # @method decrement(field, by=1)
+    # @macro [new] delegate
+    #   Delegates to the corresponding method of underlying object.
+    delegate :decrement, :to => :@record
+
+    # @method increment(field, by=1)
+    # @macro delegate
+    delegate :increment, :to => :@record
+
+    # @method toggle(field)
+    # @macro delegate
+    delegate :toggle, :to => :@record
+
+    # @method touch(field)
+    # @macro delegate
+    # This method does not modify any fields except for the timestamp itself
+    # and thus is not considered as a potential security threat.
+    delegate :touch, :to => :@record
+
+    # A proxy for +attributes+ method which removes all attributes
+    # without +:view+ permission.
+    def attributes
+      @restrictions.filter_attributes(:view, @record.attributes)
+    end
+
+    # A proxy for +update_attributes+ method which removes all attributes
+    # without +:update+ permission and invokes +#save+.
+    #
+    # @raise [Heimdallr::PermissionError]
+    def update_attributes(attributes, options={})
+      @record.with_transaction_returning_status do
+        @record.assign_attributes(attributes, options)
+        self.save
+      end
+    end
+
+    # A proxy for +update_attributes!+ method which removes all attributes
+    # without +:update+ permission and invokes +#save!+.
+    #
+    # @raise [Heimdallr::PermissionError]
+    def update_attributes(attributes, options={})
+      @record.with_transaction_returning_status do
+        @record.assign_attributes(attributes, options)
+        self.save!
+      end
+    end
+
+    # A proxy for +save+ method which verifies all of the dirty attributes to
+    # be valid for current security context.
+    #
+    # @raise [Heimdallr::PermissionError]
+    def save(options={})
+      check_save_options options
+
+      check_attributes do
+        @record.save(options)
+      end
+    end
+
+    # A proxy for +save+ method which verifies all of the dirty attributes to
+    # be valid for current security context and mandates the current record
+    # to be valid.
+    #
+    # @raise [Heimdallr::PermissionError]
+    # @raise [ActiveRecord::RecordInvalid]
+    # @raise [ActiveRecord::RecordNotSaved]
+    def save!(options={})
+      check_save_options options
+
+      check_attributes do
+        @record.save!(options)
+      end
+    end
+
+    [:delete, :destroy].each do |method|
+      class_eval(<<-EOM, __FILE__, __LINE__)
+      def #{method}
+        scope = @restrictions.request_scope(:delete)
+        if scope.where({ @record.primary_key => @record.to_key }).count != 0
+          @record.#{method}
+        end
+      end
+      EOM
+    end
+
+    # Records cannot be restricted twice.
+    #
+    # @raise [RuntimeError]
+    def restrict(context)
+      raise RuntimeError, "Records cannot be restricted twice"
+    end
+
+    # A whitelisting dispatcher for attribute-related method calls.
+    # Every unknown method is first normalized (that is, stripped of its +?+ or +=+
+    # suffix). Then, if the normalized form is whitelisted, it is passed to the
+    # underlying object as-is. Otherwise, an exception is raised.
+    #
+    # If the underlying object is an instance of ActiveRecord, then all association
+    # accesses are resolved and proxified automatically.
+    #
+    # Note that only the attribute and collection getters and setters are
+    # dispatched through this method. Every other model method should be defined
+    # as an instance method of this class in order to work.
+    #
+    # @raise [Heimdallr::PermissionError] when a non-whitelisted method is accessed
+    # @raise [Heimdallr::InsecureOperationError] when an insecure association is about
+    #   to be fetched
+    def method_missing(method, *args, &block)
+      suffix = method.to_s[-1]
+      if %w(? = !).include? suffix
+        normalized_method = method[0..-2].to_sym
+      else
+        normalized_method = method
+        suffix = nil
+      end
+
+      if defined?(ActiveRecord) && @record.is_a?(ActiveRecord::Base) &&
+          association = @record.class.reflect_on_association(method)
+        referenced = @record.send(method, *args)
+
+        if referenced.respond_to? :restrict
+          referenced.restrict(@context)
+        elsif Heimdallr.allow_insecure_associations
+          referenced
+        else
+          raise Heimdallr::InsecureOperationError,
+              "Attempt to fetch insecure association #{method}. Try #insecure."
+        end
+      elsif @record.respond_to? method
+        if [nil, '?'].include?(suffix) &&
+             @restrictions.allowed_fields[:view].include?(normalized_method)
+          # Reading an attribute
+          @record.send method, *args, &block
+        elsif suffix == '='
+          @record.send method, *args
+        else
+          raise Heimdallr::PermissionError,
+              "Non-whitelisted method #{method} is called for #{@record.inspect} on #{@action}."
+        end
+      else
+        super
+      end
+    end
+
+    # Return the underlying object.
+    #
+    # @return [ActiveRecord::Base]
+    def insecure
+      @record
+    end
+
+    # Describes the proxy and proxified object.
+    #
+    # @return [String]
+    def inspect
+      "#<Heimdallr::Proxy(#{@action}): #{@record.inspect}>"
+    end
+
+    # Return the associated security metadata. The returned hash will contain keys
+    # +:context+ and +:object+, corresponding to the parameters in
+    # {#initialize}.
+    #
+    # Such a name was deliberately selected for this method in order to reduce namespace
+    # pollution.
+    #
+    # @return [Hash]
+    def reflect_on_security
+      {
+        context: @context,
+        object:  @record
+      }
+    end
+
+    protected
+
+    # Raises an exception if any of the changed attributes are not valid
+    # for the current security context.
+    #
+    # @raise [Heimdallr::PermissionError]
+    def check_attributes
+      @record.errors.clear
+
+      if @record.new_record?
+        action = :create
+      else
+        action = :update
+      end
+
+      fixtures   = @restrictions.fixtures[action]
+      validators = @restrictions.validators[action]
+
+      @record.changed.each do |attribute|
+        value = @record.send attribute
+
+        if fixtures.has_key? attribute
+          if fixtures[attribute] != value
+            raise Heimdallr::PermissionError,
+                "Attribute #{attribute} value (#{value}) is not equal to a fixture (#{fixtures[attribute]})"
+          end
+        end
+      end
+
+      @record.heimdallr_validators = validators
+
+      yield
+    ensure
+      @record.heimdallr_validators = nil
+    end
+
+    # Raises an exception if any of the +options+ intended for use in +save+
+    # methods are potentially unsafe.
+    def check_save_options(options)
+      if options[:validate] == false
+        raise Heimdallr::InsecureOperationError,
+            "Saving while omitting validation would omit security validations too"
+      end
+    end
+  end
+end

data/lib/heimdallr/resource.rb

@@ -1,110 +1,250 @@
 module Heimdallr
+  # Heimdallr {Resource} is a boilerplate for simple creation of REST endpoints, most of which are
+  # quite similar and thus may share a lot of code.
+  #
+  # The minimal controller possible would be:
+  #
+  #     class MiceController < ApplicationController
+  #       include Heimdallr::Resource
+  #
+  #       # Class Mouse must include Heimdallr::Model.
+  #       resource_for :mouse
+  #     end
+  #
+  # Resource is built with Convention over Configuration principle in mind; that is,
+  # instead of providing complex configuration syntax, Resource consists of a lot of small, easy
+  # to override methods. If some kind of default behavior is undesirable, then one can just override
+  # the relative method in the particular controller or, say, define a module if the changes are
+  # to be shared between several controllers. You are encouraged to explore the source of this class.
+  #
+  # Resource allows to perform efficient operations on collections of objects. The
+  # {#create}, {#update} and {#destroy} actions accept both a single object/ID or an array of
+  # objects/IDs. The cardinal _modus
+  #
+  # Resource expects a method named +security_context+ to be defined either in the controller itself
+  # or, more conveniently, in any of its ancestors, likely +ApplicationController+. This method can
+  # often be aliased to +current_user+.
+  #
+  # Resource only works with ActiveRecord.
+  #
+  # See also {Resource::ClassMethods}.
   module Resource
-    extend ActiveSupport::Concern
+    # @group Actions
 
-    module ClassMethods
-      attr_reader :model
+    # +GET /resources+
+    #
+    # This action does nothing by itself, but it has a +load_all_resources+ filter attached.
+    def index
+    end
 
-      def resource_for(model, options={})
-        @model = model.to_s.capitalize.constantize
+    # +GET /resource/1+
+    #
+    # This action does nothing by itself, but it has a +load_one_resource+ filter attached.
+    def show
+    end
 
-        before_filter :load_all_resources,          only: [ :index ].concat(options[:all] || [])
-        before_filter :load_one_resource,           only: [ :show  ].concat(options[:member] || [])
-        before_filter :load_referenced_resources,   only: [ :update, :destroy ].concat(options[:collection] || [])
-      end
+    # +GET /resources/new+
+    #
+    # This action renders a JSON representation of fields whitelisted for creation.
+    # It does not include any fixtures or validations.
+    #
+    # @example
+    #   { 'fields': [ 'topic', 'content' ] }
+    def new
+      render :json => {
+        :fields => model.restrictions(security_context).allowed_fields[:create]
+      }
     end
 
-    module InstanceMethods
-      def index
+    # +POST /resources+
+    #
+    # This action creates one or more records from the passed parameters.
+    # It can accept both arrays of attribute hashes and single attribute hashes.
+    #
+    # After the creation, it calls {#render_resources}.
+    #
+    # See also {#load_referenced_resources} and {#with_objects_from_params}.
+    def create
+      with_objects_from_params do |attributes, index|
+        scoped_model.restrict(security_context).
+            create!(attributes)
       end
 
-      def show
-      end
+      render_resources
+    end
+
+    # +GET /resources/1/edit+
+    #
+    # This action renders a JSON representation of fields whitelisted for updating.
+    # See also {#new}.
+    def edit
+      render :json => {
+        :fields => model.restrict(security_context).allowed_fields[:update]
+      }
+    end
 
-      def new
-        render :json => {
-          :fields => model.restrictions(security_context).whitelist[:create]
-        }
+    # +PUT /resources/1,2+
+    #
+    # This action updates one or more records from the passed parameters.
+    # It expects resource IDs to be passed comma-separated in <tt>params[:id]</tt>,
+    # and expects them to be in the order corresponding to the order of actual
+    # attribute hashes.
+    #
+    # After the updating, it calls {#render_resources}.
+    #
+    # See also {#load_referenced_resources} and {#with_objects_from_params}.
+    def update
+      with_objects_from_params do |attributes, index|
+        @resources[index].update_attributes! attributes
       end
 
-      def create
-        model.transaction do
-          if params.has_key? model.name.underscore
-            scoped_model.new.to_proxy(security_context, :create).
-              update_attributes!(params[model.name.underscore])
-          else
-            @resources.each_with_index do |resource, index|
-              scoped_model.new.to_proxy(security_context, :create).
-                update_attributes!(params[model.name.underscore.pluralize][index])
-            end
-          end
-        end
+      render_resources
+    end
 
-        if block_given?
-          yield
-        else
-          render_modified_resources
-        end
+    # +DELETE /resources/1,2+
+    #
+    # This action destroys one or more records. It expects resource IDs to be passed
+    # comma-separated in <tt>params[:id]</tt>.
+    #
+    # See also {#load_referenced_resources}.
+    def destroy
+      model.transaction do
+        @resources.each &:destroy
       end
 
-      def edit
-        render :json => {
-          :fields => model.restrictions(security_context).whitelist[:update]
-        }
-      end
+      render :json => {}, :status => :ok
+    end
 
-      def update
-        model.transaction do
-          if params.has_key? model.name.underscore
-            @resources.first.to_proxy(security_context, :update).
-              update_attributes!(params[model.name.underscore])
-          else
-            @resources.each_with_index do |resource, index|
-              resource.to_proxy(security_context, :update).
-              update_attributes!(params[model.name.underscore.pluralize][index])
-            end
-          end
-        end
+    protected
 
-        if block_given?
-          yield
-        else
-          render_modified_resources
-        end
-      end
+    # @group Configuration
 
-      def destroy
-        model.transaction do
-          @resources.each &:destroy
-        end
+    # Return the associated model class.
+    # @return [Class] associated model
+    def model
+      self.class.model
+    end
 
-        render :json => {}, :status => :ok
-      end
+    # Return the appropriately scoped model. By default this method
+    # delegates to +self.model.scoped+; you may override it for nested
+    # resources so that it would only return the nested set.
+    #
+    # For example, this code would not allow user to perform any actions
+    # with a transaction from a wrong account, raising RecordNotFound
+    # instead:
+    #
+    #     # transactions_controller.rb
+    #     class TransactionsController < ApplicationController
+    #       include Heimdallr::Resource
+    #
+    #       resource_for :transactions
+    #
+    #       protected
+    #
+    #       def scoped_model
+    #         Account.find(params[:account_id]).transactions
+    #       end
+    #     end
+    #
+    #     # routes.rb
+    #     Foo::Application.routes.draw do
+    #       resources :accounts do
+    #         resources :transactions
+    #       end
+    #     end
+    #
+    # @return ActiveRecord scope
+    def scoped_model
+      self.model.scoped
+    end
 
-      protected
+    # Loads all resources in the current scope to +@resources+.
+    #
+    # Is automatically applied to {#index}.
+    def load_all_resources
+      @resources = scoped_model
+    end
 
-      def model
-        self.class.model
-      end
+    # Loads one resource from the current scope, referenced by <code>params[:id]</code>,
+    # to +@resource+.
+    #
+    # Is automatically applied to {#show}.
+    def load_one_resource
+      @resource  = scoped_model.find(params[:id])
+    end
 
-      def scoped_model
-        self.model.scoped
-      end
+    # Loads several resources from the current scope, referenced by <code>params[:id]</code>
+    # with a comma-separated string like "1,2,3", to +@resources+.
+    #
+    # Is automatically applied to {#update} and {#destroy}.
+    def load_referenced_resources
+      @resources = scoped_model.find(params[:id].split(','))
+    end
 
-      def load_one_resource
-        @resource  = scoped_model.find(params[:id])
-      end
+    # Render a modified collection in {#create}, {#update} and similar actions.
+    #
+    # By default, it invokes a template for +index+.
+    def render_resources
+      render :action => :index
+    end
 
-      def load_all_resources
-        @resources = scoped_model.scoped
+    # Fetch one or several objects passed in +params+ and yield them to a block,
+    # wrapping everything in a transaction.
+    #
+    # @yield [attributes, index]
+    # @yieldparam [Hash] attributes
+    # @yieldparam [Integer] index
+    def with_objects_from_params
+      model.transaction do
+        if params.has_key? model.name.underscore
+          yield params[model.name.underscore], 0
+        else
+          params[model.name.underscore.pluralize].
+                each_with_index do |attributes, index|
+            yield attributes, index
+          end
+        end
       end
+    end
 
-      def load_referenced_resources
-        @resources = scoped_model.find(params[:id].split(','))
-      end
+    extend ActiveSupport::Concern
+
+    # Class methods for {Heimdallr::Resource}. See also +ActiveSupport::Concern+.
+    module ClassMethods
+      # Returns the attached model class.
+      # @return [Class]
+      attr_reader :model
+
+      # Attaches this resource to a model.
+      #
+      # Note that ActiveSupport +before_filter+ _replaces_ the list of actions for specified
+      # filter and not appends to it. For example, the following code will only run +filter_a+
+      # when +bar+ action is invoked:
+      #
+      #     class FooController < ApplicationController
+      #       before_filter :filter_a, :only => :foo
+      #       before_filter :filter_a, :only => :bar
+      #
+      #       def foo; end
+      #       def bar; end
+      #     end
+      #
+      # For convenience, you can pass additional actions to register with default filters in
+      # +options+. It is also possible to use +append_before_filter+.
+      #
+      # @param [Class] model An ActiveModel or ActiveRecord model class.
+      # @option options [Array<Symbol>] :index
+      #   Additional actions to be covered by {Heimdallr::Resource#load_all_resources}.
+      # @option options [Array<Symbol>] :member
+      #   Additional actions to be covered by {Heimdallr::Resource#load_one_resource}.
+      # @option options [Array<Symbol>] :collection
+      #   Additional actions to be covered by {Heimdallr::Resource#load_referenced_resources}.
+      def resource_for(model, options={})
+        @model = model.to_s.camelize.constantize
 
-      def render_modified_resources
-        render :action => :index
+        before_filter :load_all_resources,          only: [ :index ].concat(options[:all] || [])
+        before_filter :load_one_resource,           only: [ :show  ].concat(options[:member] || [])
+        before_filter :load_referenced_resources,   only: [ :update, :destroy ].concat(options[:collection] || [])
       end
     end
   end