heimdallr 0.0.2 → 1.0.0.RC2

data/README.md

@@ -19,17 +19,19 @@ class Article < ActiveRecord::Base
   restrict do |user|
     if user.admin? || user == self.owner
       # Administrator or owner can do everything
-      can :fetch
-      can [:view, :create, :update, :destroy]
+      scope :fetch
+      scope :destroy
+      can [:view, :create, :update]
     else
       # Other users can view only non-classified articles...
-      can :fetch, -> { where('secrecy_level < ?', 5) }
+      scope :fetch, -> { where('secrecy_level < ?', 5) }
 
       # ... and see all fields except the actual security level...
       can    :view
       cannot :view, [:secrecy_level]
 
       # ... and can create them with certain restrictions.
+      can :create, %w(content)
       can [:create, :update], {
         owner:         user,
         secrecy_level: { inclusion: { in: 0..4 } }
@@ -52,12 +54,17 @@ secure = Article.restrict(johndoe)
 # Use any ARel methods:
 secure.pluck(:content)
 # => ["Nothing happens", "Hello World"]
-secure.find(1).secrecy_level
-# => nil
 
 # Everything should be permitted explicitly:
 secure.first.delete
 # ! Heimdallr::PermissionError is raised
+secure.find(1).secrecy_level
+# ! Heimdallr::PermissionError is raised
+
+# There is a helper for views to be easily written:
+view_passed = secure.first.implicit
+view_passed.secrecy_level
+# => nil
 
 # If only a single value is possible, it is inferred automatically:
 secure.create! content: "My second article"
@@ -65,7 +72,7 @@ secure.create! content: "My second article"
 
 # ... and cannot be changed:
 secure.create! owner: admin, content: "I'm a haxx0r"
-# ! ActiveRecord::RecordInvalid is raised
+# ! Heimdallr::PermissionError is raised
 
 # You can use any valid ActiveRecord validators, too:
 secure.create! content: "Top Secret", secrecy_level: 10
@@ -78,26 +85,17 @@ secure.find 2
 # -- No, it is not.
 ```
 
-The DSL is described in documentation for [Heimdallr::Model](http://rubydoc.info/gems/heimdallr/0.0.2/Heimdallr/Model).
-
-Note that Heimdallr is designed with three goals in mind, in the following order:
-
- * Preventing malicious modifications
- * Preventing information leaks
- * Being convenient to use
-
-Due to the last one, not all methods will raise an exception on invalid access; some will silently drop the offending
-attribute or simply return `nil`. This is clearly described in the documentation, done intentionally and isn't
-going to change.
+The DSL is described in documentation for [Heimdallr::Model](http://rubydoc.info/gems/heimdallr/1.0.0.RC2/Heimdallr/Model).
 
-REST interface
---------------
+Ideology
+--------
 
-Heimdallr also favors REST pattern; while its use is not mandated, a Heimdallr::Resource module is provided, which
-implements all standard REST actions with the extension of allowing to pass multiple models at once, and also enables
-one to introspect all writable fields with `new` and `edit` actions.
+Heimdallr aims to make security explicit, but nevertheless convenient. It does not allow one to call any
+implicit operations which may be used maliciously; instead, it forces you to explicitly call `#insecure`
+method which returns the underlying object. This single point of entry is easily recognizable with code.
 
-The interface is described in documentation for [Heimdallr::Resource](http://rubydoc.info/gems/heimdallr/0.0.2/Heimdallr/Resource).
+Heimdallr would raise exceptions in all cases of forbidden or potentially unsecure access except for attribute
+reading to allow for writing uncrufted code in templates (particularly [JBuilder](http://github.com/rails/jbuilder) ones).
 
 Compatibility
 -------------

data/README.yard.md

@@ -19,17 +19,19 @@ class Article < ActiveRecord::Base
   restrict do |user|
     if user.admin? || user == self.owner
       # Administrator or owner can do everything
-      can :fetch
-      can [:view, :create, :update, :destroy]
+      scope :fetch
+      scope :destroy
+      can [:view, :create, :update]
     else
       # Other users can view only non-classified articles...
-      can :fetch, -> { where('secrecy_level < ?', 5) }
+      scope :fetch, -> { where('secrecy_level < ?', 5) }
 
       # ... and see all fields except the actual security level...
       can    :view
       cannot :view, [:secrecy_level]
 
       # ... and can create them with certain restrictions.
+      can :create, %w(content)
       can [:create, :update], {
         owner:         user,
         secrecy_level: { inclusion: { in: 0..4 } }
@@ -52,12 +54,17 @@ secure = Article.restrict(johndoe)
 # Use any ARel methods:
 secure.pluck(:content)
 # => ["Nothing happens", "Hello World"]
-secure.find(1).secrecy_level
-# => nil
 
 # Everything should be permitted explicitly:
 secure.first.delete
 # ! Heimdallr::PermissionError is raised
+secure.find(1).secrecy_level
+# ! Heimdallr::PermissionError is raised
+
+# There is a helper for views to be easily written:
+view_passed = secure.first.implicit
+view_passed.secrecy_level
+# => nil
 
 # If only a single value is possible, it is inferred automatically:
 secure.create! content: "My second article"
@@ -65,7 +72,7 @@ secure.create! content: "My second article"
 
 # ... and cannot be changed:
 secure.create! owner: admin, content: "I'm a haxx0r"
-# ! ActiveRecord::RecordInvalid is raised
+# ! Heimdallr::PermissionError is raised
 
 # You can use any valid ActiveRecord validators, too:
 secure.create! content: "Top Secret", secrecy_level: 10
@@ -80,24 +87,15 @@ secure.find 2
 
 The DSL is described in documentation for {Heimdallr::Model}.
 
-Note that Heimdallr is designed with three goals in mind, in the following order:
-
- * Preventing malicious modifications
- * Preventing information leaks
- * Being convenient to use
-
-Due to the last one, not all methods will raise an exception on invalid access; some will silently drop the offending
-attribute or simply return `nil`. This is clearly described in the documentation, done intentionally and isn't
-going to change.
-
-REST interface
---------------
+Ideology
+--------
 
-Heimdallr also favors REST pattern; while its use is not mandated, a Heimdallr::Resource module is provided, which
-implements all standard REST actions with the extension of allowing to pass multiple models at once, and also enables
-one to introspect all writable fields with `new` and `edit` actions.
+Heimdallr aims to make security explicit, but nevertheless convenient. It does not allow one to call any
+implicit operations which may be used maliciously; instead, it forces you to explicitly call `#insecure`
+method which returns the underlying object. This single point of entry is easily recognizable with code.
 
-The interface is described in documentation for {Heimdallr::Resource}.
+Heimdallr would raise exceptions in all cases of forbidden or potentially unsecure access except for attribute
+reading to allow for writing uncrufted code in templates (particularly [JBuilder](http://github.com/rails/jbuilder) ones).
 
 Compatibility
 -------------

data/heimdallr.gemspec

@@ -3,17 +3,15 @@ $:.push File.expand_path("../lib", __FILE__)
 
 Gem::Specification.new do |s|
   s.name        = "heimdallr"
-  s.version     = "0.0.2"
-  s.authors     = ["Peter Zotov"]
-  s.email       = ["whitequark@whitequark.org"]
+  s.version     = "1.0.0.RC2"
+  s.authors     = ["Peter Zotov", "Boris Staal"]
+  s.email       = ["whitequark@whitequark.org", "boris@roundlake.ru"]
   s.homepage    = "http://github.com/roundlake/heimdallr"
   s.summary     = %q{Heimdallr is an ActiveModel extension which provides object- and field-level access control.}
   s.description = %q{Heimdallr aims to provide an easy to configure and efficient object- and field-level access
  control solution, reusing proven patterns from gems like CanCan and allowing one to manage permissions in a very
  fine-grained manner.}
 
-  s.rubyforge_project = "heimdallr"
-
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }

data/lib/heimdallr.rb

@@ -1,15 +1,7 @@
 require "active_support"
+require "active_support/core_ext/module/delegation"
 require "active_model"
 
-require "heimdallr/version"
-
-require "heimdallr/proxy/collection"
-require "heimdallr/proxy/record"
-require "heimdallr/validator"
-require "heimdallr/evaluator"
-require "heimdallr/model"
-require "heimdallr/resource"
-
 # See {file:README.yard}.
 module Heimdallr
   class << self
@@ -33,9 +25,10 @@ module Heimdallr
     #
     # @return [Boolean]
     attr_accessor :allow_insecure_associations
-    self.allow_insecure_associations = false
   end
 
+  self.allow_insecure_associations = false
+
   # {PermissionError} is raised when a security policy prevents
   # a called operation from being executed.
   class PermissionError < StandardError; end
@@ -43,4 +36,14 @@ module Heimdallr
   # {InsecureOperationError} is raised when a potentially unsafe
   # operation is about to be executed.
   class InsecureOperationError < StandardError; end
-end
+
+  # Heimdallr uses proxies to control access to restricted scopes and collections.
+  module Proxy; end
+end
+
+require "heimdallr/proxy/collection"
+require "heimdallr/proxy/record"
+require "heimdallr/validator"
+require "heimdallr/evaluator"
+require "heimdallr/model"
+require "heimdallr/legacy_resource"

data/lib/heimdallr/evaluator.rb

@@ -6,18 +6,20 @@ module Heimdallr
   # is whitelisting safe actions, not blacklisting unsafe ones. This is by design
   # and is not going to change.
   #
+  # The field +#id+ is whitelisted by default.
+  #
   # The DSL consists of three functions: {#scope}, {#can} and {#cannot}.
   class Evaluator
     attr_reader :allowed_fields, :fixtures, :validators
 
-    # Create a new Evaluator for the ActiveModel-descending class +model_class+,
+    # Create a new Evaluator for the +ActiveRecord+-derived class +model_class+,
     # and use +block+ to infer restrictions for any security context passed.
     def initialize(model_class, block)
       @model_class, @block = model_class, block
 
       @scopes         = {}
       @allowed_fields = {}
-      @validations    = {}
+      @validators     = {}
       @fixtures       = {}
     end
 
@@ -36,7 +38,7 @@ module Heimdallr
     #   This form accepts an implicit lambda.
     #
     #   @example
-    #       scope :fetch do
+    #       scope :fetch do |user|
     #         if user.manager?
     #           scoped
     #         else
@@ -72,15 +74,18 @@ module Heimdallr
     # @param [Symbol, Array<Symbol>] actions one or more action names
     # @param [Hash<Hash, Object>] fields field restrictions
     def can(actions, fields=@model_class.attribute_names)
-      Array(actions).each do |action|
+      Array(actions).map(&:to_sym).each do |action|
         case fields
         when Hash # a list of validations
-          @allowed_fields[action] += fields.keys
-          @validations[action]    += create_validators(fields)
-          @fixtures[action].merge extract_fixtures(fields)
+          @allowed_fields[action] += fields.keys.map(&:to_sym)
+          @validators[action]     += create_validators(fields)
+
+          fixtures = extract_fixtures(fields)
+          @fixtures[action] = @fixtures[action].merge fixtures
+          @allowed_fields[action] -= fixtures.keys
 
         else # an array or a field name
-          @allowed_fields[action] += Array(fields)
+          @allowed_fields[action] += Array(fields).map(&:to_sym)
         end
       end
     end
@@ -91,8 +96,8 @@ module Heimdallr
     # @param [Symbol, Array<Symbol>] actions one or more action names
     # @param [Array<Symbol>] fields field list
     def cannot(actions, fields)
-      Array(actions).each do |action|
-        @allowed_fields[action] -= fields
+      Array(actions).map(&:to_sym).each do |action|
+        @allowed_fields[action] -= fields.map(&:to_sym)
         @fixtures.delete_at *fields
       end
     end
@@ -104,25 +109,59 @@ module Heimdallr
     # @param scope name of the scope
     # @param basic_scope the scope to which scope +name+ will be applied. Defaults to +:fetch+.
     #
-    # @return ActiveRecord scope
-    def request_scope(name=:fetch, basic_scope=request_scope(:fetch))
-      if name == :fetch || !@scopes.has_key?(name)
-        fetch_scope = @model_class.instance_exec(&@scopes[:fetch])
+    # @return +ActiveRecord+ scope.
+    #
+    # @raise [RuntimeError] if the scope is not defined
+    def request_scope(name=:fetch, basic_scope=nil)
+      unless @scopes.has_key?(name)
+        raise RuntimeError, "The #{name.inspect} scope does not exist"
+      end
+
+      if name == :fetch && basic_scope.nil?
+        @model_class.instance_exec(&@scopes[:fetch])
       else
-        basic_scope.instance_exec(&@scopes[name])
+        (basic_scope || request_scope(:fetch)).instance_exec(&@scopes[name])
       end
     end
 
+    # Check if any explicit restrictions were defined for +action+.
+    # +can :create, []+ _is_ an explicit restriction for action +:create+.
+    #
+    # @return Boolean
+    def can?(action)
+      @allowed_fields.include? action
+    end
+
+    # Return a Hash to be mixed in in +reflect_on_security+ methods of {Proxy::Collection}
+    # and {Proxy::Record}.
+    def reflection
+      {
+        operations: [ :view, :create, :update ].select { |op| can? op }
+      }
+    end
+
     # Compute the restrictions for a given +context+. Invokes a +block+ passed to the
     # +initialize+ once.
+    #
+    # @raise [RuntimeError] if the evaluated block did not define a set of valid restrictions
     def evaluate(context)
       if context != @last_context
         @scopes         = {}
         @allowed_fields = Hash.new { [] }
         @validators     = Hash.new { [] }
-        @fixtures       = Hash.new { [] }
+        @fixtures       = Hash.new { {} }
+
+        @allowed_fields[:view] += [ :id ]
 
-        instance_exec context, &block
+        instance_exec context, &@block
+
+        unless @scopes[:fetch]
+          raise RuntimeError, "A :fetch scope must be defined"
+        end
+
+        @allowed_fields.each do |action, fields|
+          fields.uniq!
+        end
 
         [@scopes, @allowed_fields, @validators, @fixtures].
               map(&:freeze)
@@ -139,7 +178,7 @@ module Heimdallr
     #
     # @return [Array<ActiveModel::Validator>]
     def create_validators(fields)
-      validators = {}
+      validators = []
 
       fields.each do |attribute, validations|
         next unless validations.is_a? Hash
@@ -153,7 +192,7 @@ module Heimdallr
             raise ArgumentError, "Unknown validator: '#{key}'"
           end
 
-          validators[attribute] = validator.new(_parse_validates_options(options).merge(:attributes => [ attribute ]))
+          validators << validator.new(_parse_validates_options(options).merge(:attributes => [ attribute ]))
         end
       end
 
@@ -167,7 +206,7 @@ module Heimdallr
       fields.each do |attribute, options|
         next if options.is_a? Hash
 
-        fixtures[attribute] = options
+        fixtures[attribute.to_sym] = options
       end
 
       fixtures

data/lib/heimdallr/{resource.rb → legacy_resource.rb}

@@ -1,5 +1,8 @@
 module Heimdallr
-  # Heimdallr {Resource} is a boilerplate for simple creation of REST endpoints, most of which are
+  #
+  # @deprecated Will be removed ASAP. Please don't use it in favour of http://github.com/roundlake/heimdallr-resource/
+  #
+  # Heimdallr {LegacyResource} 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:
@@ -28,19 +31,21 @@ module Heimdallr
   # Resource only works with ActiveRecord.
   #
   # See also {Resource::ClassMethods}.
-  module Resource
+  module LegacyResource
     # @group Actions
 
     # +GET /resources+
     #
     # This action does nothing by itself, but it has a +load_all_resources+ filter attached.
     def index
+      render_data
     end
 
     # +GET /resource/1+
     #
     # This action does nothing by itself, but it has a +load_one_resource+ filter attached.
     def show
+      render_data
     end
 
     # +GET /resources/new+
@@ -61,16 +66,15 @@ module Heimdallr
     # 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}.
+    # After the creation, it calls {#render_data}.
     #
     # 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)
+      with_objects_from_params(replace: true) do |object, attributes|
+        restricted_model.create(attributes)
       end
 
-      render_resources
+      render_data verify: true
     end
 
     # +GET /resources/1/edit+
@@ -79,7 +83,7 @@ module Heimdallr
     # See also {#new}.
     def edit
       render :json => {
-        :fields => model.restrict(security_context).allowed_fields[:update]
+        :fields => model.restrictions(security_context).allowed_fields[:update]
       }
     end
 
@@ -90,15 +94,15 @@ module Heimdallr
     # and expects them to be in the order corresponding to the order of actual
     # attribute hashes.
     #
-    # After the updating, it calls {#render_resources}.
+    # After the updating, it calls {#render_data}.
     #
     # See also {#load_referenced_resources} and {#with_objects_from_params}.
     def update
-      with_objects_from_params do |attributes, index|
-        @resources[index].update_attributes! attributes
+      with_objects_from_params do |object, attributes|
+        object.update_attributes attributes
       end
 
-      render_resources
+      render_data verify: true
     end
 
     # +DELETE /resources/1,2+
@@ -108,8 +112,8 @@ module Heimdallr
     #
     # See also {#load_referenced_resources}.
     def destroy
-      model.transaction do
-        @resources.each &:destroy
+      with_objects_from_params do |object, attributes|
+        object.destroy
       end
 
       render :json => {}, :status => :ok
@@ -158,34 +162,50 @@ module Heimdallr
       self.model.scoped
     end
 
+    # Return the scoped and restricted model. By default this method
+    # restricts the result of {#scoped_model} with +security_context+,
+    # which is expected to be defined on this class or its ancestors.
+    def restricted_model
+      scoped_model.restrict(security_context, implicit: true)
+    end
+
     # Loads all resources in the current scope to +@resources+.
     #
     # Is automatically applied to {#index}.
     def load_all_resources
-      @resources = scoped_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])
+      @multiple_resources = true
+      @resources = restricted_model
     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}.
+    # Is automatically applied to {#show}, {#update} and {#destroy}.
     def load_referenced_resources
-      @resources = scoped_model.find(params[:id].split(','))
+      if params[:id][0] == '*'
+        @multiple_resources = true
+        @resources = restricted_model.find(params[:id][1..-1].split(','))
+      else
+        @multiple_resources = false
+        @resource  = restricted_model.find(params[:id])
+      end
     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
+    def render_data(options={})
+      if @multiple_resources
+        if options[:verify] && @resources.any?(&:invalid?)
+          render :json => { errors: @resources.map(&:errors) }, :status => :unprocessable_entity
+        else
+          render :action => :index
+        end
+      else
+        if options[:verify] && @resource.invalid?
+          render :json => @resource.errors, :status => :unprocessable_entity
+        else
+          render :action => :show
+        end
+      end
     end
 
     # Fetch one or several objects passed in +params+ and yield them to a block,
@@ -194,14 +214,28 @@ module Heimdallr
     # @yield [attributes, index]
     # @yieldparam [Hash] attributes
     # @yieldparam [Integer] index
-    def with_objects_from_params
+    def with_objects_from_params(options={})
       model.transaction do
-        if params.has_key? model.name.underscore
-          yield params[model.name.underscore], 0
+        if @multiple_resources
+          begin
+            name = model.name.underscore.pluralize
+            if params[name].is_a? Hash
+              enumerator = params[name].keys.each
+            else
+              enumerator = params[name].each_index
+            end
+
+            result = enumerator.map do |index|
+              yield(@resources[index.to_i], params[name][index])
+            end
+          ensure
+            @resources = result if options[:replace]
+          end
         else
-          params[model.name.underscore.pluralize].
-                each_with_index do |attributes, index|
-            yield attributes, index
+          begin
+            result = yield(@resource, params[model.name.underscore])
+          ensure
+            @resource  = result if options[:replace]
           end
         end
       end
@@ -232,7 +266,7 @@ module Heimdallr
       # 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.
+      # @param [Class] model an +ActiveRecord+-derived model class
       # @option options [Array<Symbol>] :index
       #   Additional actions to be covered by {Heimdallr::Resource#load_all_resources}.
       # @option options [Array<Symbol>] :member
@@ -242,9 +276,8 @@ module Heimdallr
       def resource_for(model, options={})
         @model = model.to_s.camelize.constantize
 
-        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] || [])
+        before_filter :load_all_resources,        only: [ :index ].concat(options[:all] || [])
+        before_filter :load_referenced_resources, only: [ :show, :update, :destroy ].concat(options[:referenced] || [])
       end
     end
   end

data/lib/heimdallr/model.rb

@@ -10,6 +10,9 @@ module Heimdallr
   #       end
   #     end
   #
+  # {Heimdallr::Model} should be included prior to any other modules, as it may omit
+  # some named scopes defined by those if it is not.
+  #
   # @todo Improve description
   module Model
     extend ActiveSupport::Concern
@@ -28,11 +31,11 @@ module Heimdallr
       #   @param [Object] context security context
       #   @param [Symbol] action  kind of actions which will be performed
       #   @return [Proxy::Collection]
-      def restrict(context=nil, &block)
+      def restrict(context=nil, options={}, &block)
         if block
-          @restrictions = Evaluator.new(self, &block)
+          @restrictions = Evaluator.new(self, block)
         else
-          Proxy::Collection.new(context, restrictions(context).request_scope)
+          Proxy::Collection.new(context, restrictions(context).request_scope, options)
         end
       end
 
@@ -42,13 +45,40 @@ module Heimdallr
       def restrictions(context)
         @restrictions.evaluate(context)
       end
+
+      # @api private
+      #
+      # An internal attribute to store the list of user-defined name scopes.
+      # It is required because ActiveRecord does not provide any introspection for
+      # named scopes.
+      attr_accessor :heimdallr_scopes
+
+      # An interceptor for named scopes which adds them to {#heimdallr_scopes} list.
+      def scope(name, *args)
+        self.heimdallr_scopes ||= []
+        self.heimdallr_scopes.push name
+
+        super
+      end
+
+      # @api private
+      #
+      # An internal attribute to store the list of user-defined relation-like methods
+      # which return ActiveRecord family objects and can be automatically restricted.
+      attr_accessor :heimdallr_relations
+
+      # A DSL method for defining relation-like methods.
+      def heimdallr_relation(*methods)
+        self.heimdallr_relations ||= []
+        self.heimdallr_relations  += methods.map(&:to_sym)
+      end
     end
 
     # Return a secure proxy object for this record.
     #
     # @return [Record::Proxy]
-    def restrict(context, action)
-      Record::Proxy.new(context, self)
+    def restrict(context, options={})
+      Proxy::Record.new(context, self, options)
     end
 
     # @api private
@@ -57,9 +87,16 @@ module Heimdallr
     # the context in which this object is currently being saved.
     attr_accessor :heimdallr_validators
 
+    # @api private
+    #
+    # An internal method to run Heimdallr security validators, when applicable.
+    def heimdallr_validations
+      validates_with Heimdallr::Validator
+    end
+
     def self.included(klass)
-      klass.const_eval do
-        validates_with Heimdallr::Validator
+      klass.class_eval do
+        validate :heimdallr_validations
       end
     end
   end

data/lib/heimdallr/proxy/collection.rb

@@ -2,27 +2,225 @@ 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.
+  #
+  # There are two kinds of collection proxies, explicit and implicit, which instantiate
+  # the corresponding types of record proxies. See also {Proxy::Record}.
   class Proxy::Collection
+    include Enumerable
+
     # Create a collection proxy.
-    # @param context security context
-    # @param object  proxified scope
-    def initialize(context, scope)
-      @context, @scope = context, scope
+    #
+    # The +scope+ is expected to be already restricted with +:fetch+ scope.
+    #
+    # @param context  security context
+    # @param scope    proxified scope
+    # @option options [Boolean] implicit proxy type
+    def initialize(context, scope, options={})
+      @context, @scope, @options = context, scope, options
 
-      @restrictions = @object.class.restrictions(context)
+      @restrictions = @scope.restrictions(context)
     end
 
     # Collections cannot be restricted twice.
     #
     # @raise [RuntimeError]
-    def restrict(context)
+    def restrict(*args)
       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
+    # @private
+    # @macro [attach] delegate_as_constructor
+    #   A proxy for +$1+ method which adds fixtures to the attribute list and
+    #   returns a restricted record.
+    def self.delegate_as_constructor(name, method)
+      class_eval(<<-EOM, __FILE__, __LINE__)
+      def #{name}(attributes={})
+        record = @restrictions.request_scope(:fetch).new.restrict(@context, @options)
+        record.#{method}(attributes.merge(@restrictions.fixtures[:create]))
+        record
+      end
+      EOM
+    end
+
+    # @private
+    # @macro [attach] delegate_as_scope
+    #   A proxy for +$1+ method which returns a restricted scope.
+    def self.delegate_as_scope(name)
+      class_eval(<<-EOM, __FILE__, __LINE__)
+      def #{name}(*args)
+        Proxy::Collection.new(@context, @scope.#{name}(*args), @options)
+      end
+      EOM
+    end
+
+    # @private
+    # @macro [attach] delegate_as_destroyer
+    #   A proxy for +$1+ method which works on a +:delete+ scope.
+    def self.delegate_as_destroyer(name)
+      class_eval(<<-EOM, __FILE__, __LINE__)
+      def #{name}(*args)
+        @restrictions.request_scope(:delete, @scope).#{name}(*args)
+      end
+      EOM
+    end
+
+    # @private
+    # @macro [attach] delegate_as_record
+    #   A proxy for +$1+ method which returns a restricted record.
+    def self.delegate_as_record(name)
+      class_eval(<<-EOM, __FILE__, __LINE__)
+      def #{name}(*args)
+        @scope.#{name}(*args).restrict(@context, @options)
+      end
+      EOM
+    end
+
+    # @private
+    # @macro [attach] delegate_as_records
+    #   A proxy for +$1+ method which returns an array of restricted records.
+    def self.delegate_as_records(name)
+      class_eval(<<-EOM, __FILE__, __LINE__)
+      def #{name}(*args)
+        @scope.#{name}(*args).map do |element|
+          element.restrict(@context, @options)
+        end
+      end
+      EOM
+    end
+
+    # @private
+    # @macro [attach] delegate_as_value
+    #   A proxy for +$1+ method which returns a raw value.
+    def self.delegate_as_value(name)
+      class_eval(<<-EOM, __FILE__, __LINE__)
+      def #{name}(*args)
+        @scope.#{name}(*args)
+      end
+      EOM
+    end
+
+    delegate_as_constructor :build,   :assign_attributes
+    delegate_as_constructor :new,     :assign_attributes
+    delegate_as_constructor :create,  :update_attributes
+    delegate_as_constructor :create!, :update_attributes!
+
+    delegate_as_scope :scoped
+    delegate_as_scope :uniq
+    delegate_as_scope :where
+    delegate_as_scope :joins
+    delegate_as_scope :includes
+    delegate_as_scope :eager_load
+    delegate_as_scope :preload
+    delegate_as_scope :lock
+    delegate_as_scope :limit
+    delegate_as_scope :offset
+    delegate_as_scope :order
+    delegate_as_scope :reorder
+    delegate_as_scope :reverse_order
+    delegate_as_scope :extending
+
+    delegate_as_value :empty?
+    delegate_as_value :any?
+    delegate_as_value :many?
+    delegate_as_value :include?
+    delegate_as_value :exists?
+    delegate_as_value :size
+    delegate_as_value :length
+
+    delegate_as_value :calculate
+    delegate_as_value :count
+    delegate_as_value :average
+    delegate_as_value :sum
+    delegate_as_value :maximum
+    delegate_as_value :minimum
+    delegate_as_value :pluck
+
+    delegate_as_destroyer :delete
+    delegate_as_destroyer :delete_all
+    delegate_as_destroyer :destroy
+    delegate_as_destroyer :destroy_all
+
+    delegate_as_record  :first
+    delegate_as_record  :first!
+    delegate_as_record  :last
+    delegate_as_record  :last!
+
+    delegate_as_records :all
+    delegate_as_records :to_a
+    delegate_as_records :to_ary
+
+    # A proxy for +find+ which restricts the returned record or records.
+    #
+    # @return [Proxy::Record, Array<Proxy::Record>]
+    def find(*args)
+      result = @scope.find(*args)
+
+      if result.is_a? Enumerable
+        result.map do |element|
+          element.restrict(@context, @options)
+        end
+      else
+        result.restrict(@context, @options)
+      end
+    end
+
+    # A proxy for +each+ which restricts the yielded records.
+    #
+    # @yield [record]
+    # @yieldparam [Proxy::Record] record
+    def each
+      @scope.each do |record|
+        yield record.restrict(@context, @options)
+      end
+    end
+
+    # Wraps a scope or a record in a corresponding proxy.
+    def method_missing(method, *args)
+      if method =~ /^find_all_by/
+        @scope.send(method, *args).map do |element|
+          element.restrict(@context, @options)
+        end
+      elsif method =~ /^find_by/
+        @scope.send(method, *args).restrict(@context, @options)
+      elsif @scope.heimdallr_scopes && @scope.heimdallr_scopes.include?(method)
+        Proxy::Collection.new(@context, @scope.send(method, *args), @options)
+      elsif @scope.respond_to? method
+        raise InsecureOperationError,
+            "Potentially insecure method #{method} was called"
+      else
+        super
+      end
+    end
+
+    # Return the underlying scope.
+    #
+    # @return ActiveRecord scope
+    def insecure
+      @scope
+    end
+
+    # Describes the proxy and proxified scope.
+    #
+    # @return [String]
+    def inspect
+      "#<Heimdallr::Proxy::Collection: #{@scope.to_sql}>"
+    end
+
+    # Return the associated security metadata. The returned hash will contain keys
+    # +:context+, +:scope+ and +:options+, corresponding to the parameters in
+    # {#initialize}, and +:model+, representing the model class.
+    #
+    # Such a name was deliberately selected for this method in order to reduce namespace
+    # pollution.
+    #
+    # @return [Hash]
+    def reflect_on_security
+      {
+        model:   @scope,
+        context: @context,
+        scope:   @scope,
+        options: @options
+      }.merge(@restrictions.reflection)
     end
   end
 end

data/lib/heimdallr/proxy/record.rb

@@ -5,12 +5,18 @@ module Heimdallr
   #
   # The #touch method call isn't considered a security threat and as such, it is
   # forwarded to the underlying object directly.
+  #
+  # Record proxies can be of two types, implicit and explicit. Implicit proxies
+  # return +nil+ on access to methods forbidden by the current security context;
+  # explicit proxies raise an {Heimdallr::PermissionError} instead.
   class Proxy::Record
     # Create a record proxy.
-    # @param context security context
-    # @param object  proxified record
-    def initialize(context, record)
-      @context, @record = context, record
+    #
+    # @param context  security context
+    # @param object   proxified record
+    # @option options [Boolean] implicit proxy type
+    def initialize(context, record, options={})
+      @context, @record, @options = context, record, options
 
       @restrictions = @record.class.restrictions(context)
     end
@@ -37,28 +43,34 @@ module Heimdallr
     # A proxy for +attributes+ method which removes all attributes
     # without +:view+ permission.
     def attributes
-      @restrictions.filter_attributes(:view, @record.attributes)
+      @record.attributes.tap do |attributes|
+        attributes.keys.each do |key|
+          unless @restrictions.allowed_fields[:view].include? key.to_sym
+            attributes[key] = nil
+          end
+        end
+      end
     end
 
-    # A proxy for +update_attributes+ method which removes all attributes
-    # without +:update+ permission and invokes +#save+.
+    # A proxy for +update_attributes+ method.
+    # See also {#save}.
     #
     # @raise [Heimdallr::PermissionError]
     def update_attributes(attributes, options={})
       @record.with_transaction_returning_status do
         @record.assign_attributes(attributes, options)
-        self.save
+        save
       end
     end
 
-    # A proxy for +update_attributes!+ method which removes all attributes
-    # without +:update+ permission and invokes +#save!+.
+    # A proxy for +update_attributes!+ method.
+    # See also {#save!}.
     #
     # @raise [Heimdallr::PermissionError]
-    def update_attributes(attributes, options={})
+    def update_attributes!(attributes, options={})
       @record.with_transaction_returning_status do
         @record.assign_attributes(attributes, options)
-        self.save!
+        save!
       end
     end
 
@@ -93,13 +105,35 @@ module Heimdallr
       class_eval(<<-EOM, __FILE__, __LINE__)
       def #{method}
         scope = @restrictions.request_scope(:delete)
-        if scope.where({ @record.primary_key => @record.to_key }).count != 0
+        if scope.where({ @record.class.primary_key => @record.to_key }).count != 0
           @record.#{method}
         end
       end
       EOM
     end
 
+    # @method valid?
+    # @macro delegate
+    delegate :valid?, :to => :@record
+
+    # @method invalid?
+    # @macro delegate
+    delegate :invalid?, :to => :@record
+
+    # @method errors
+    # @macro delegate
+    delegate :errors, :to => :@record
+
+    # @method assign_attributes
+    # @macro delegate
+    delegate :assign_attributes, :to => :@record
+
+    # Class name of the underlying model.
+    # @return [String]
+    def class_name
+      @record.class.name
+    end
+
     # Records cannot be restricted twice.
     #
     # @raise [RuntimeError]
@@ -131,28 +165,36 @@ module Heimdallr
         suffix = nil
       end
 
-      if defined?(ActiveRecord) && @record.is_a?(ActiveRecord::Base) &&
-          association = @record.class.reflect_on_association(method)
+      if (defined?(ActiveRecord) && @record.is_a?(ActiveRecord::Reflection) &&
+          association = @record.class.reflect_on_association(method)) ||
+         (!@record.class.heimdallr_relations.nil? &&
+          @record.class.heimdallr_relations.include?(normalized_method))
         referenced = @record.send(method, *args)
 
-        if referenced.respond_to? :restrict
-          referenced.restrict(@context)
+        if referenced.nil?
+          nil
+        elsif referenced.respond_to? :restrict
+          referenced.restrict(@context, @options)
         elsif Heimdallr.allow_insecure_associations
           referenced
         else
           raise Heimdallr::InsecureOperationError,
-              "Attempt to fetch insecure association #{method}. Try #insecure."
+              "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
+        if [nil, '?'].include?(suffix)
+          if @restrictions.allowed_fields[:view].include?(normalized_method)
+            @record.send method, *args, &block
+          elsif @options[:implicit]
+            nil
+          else
+            raise Heimdallr::PermissionError, "Attempt to fetch non-whitelisted attribute #{method}"
+          end
         elsif suffix == '='
           @record.send method, *args
         else
           raise Heimdallr::PermissionError,
-              "Non-whitelisted method #{method} is called for #{@record.inspect} on #{@action}."
+              "Non-whitelisted method #{method} is called for #{@record.inspect} "
         end
       else
         super
@@ -166,16 +208,30 @@ module Heimdallr
       @record
     end
 
+    # Return an implicit variant of this proxy.
+    #
+    # @return [Heimdallr::Proxy::Record]
+    def implicit
+      Proxy::Record.new(@context, @record, @options.merge(implicit: true))
+    end
+
+    # Return an explicit variant of this proxy.
+    #
+    # @return [Heimdallr::Proxy::Record]
+    def explicit
+      Proxy::Record.new(@context, @record, @options.merge(implicit: false))
+    end
+
     # Describes the proxy and proxified object.
     #
     # @return [String]
     def inspect
-      "#<Heimdallr::Proxy(#{@action}): #{@record.inspect}>"
+      "#<Heimdallr::Proxy::Record: #{@record.inspect}>"
     end
 
     # Return the associated security metadata. The returned hash will contain keys
-    # +:context+ and +:object+, corresponding to the parameters in
-    # {#initialize}.
+    # +:context+, +:record+, +:options+, corresponding to the parameters in
+    # {#initialize}, and +:model+, representing the model class.
     #
     # Such a name was deliberately selected for this method in order to reduce namespace
     # pollution.
@@ -183,9 +239,11 @@ module Heimdallr
     # @return [Hash]
     def reflect_on_security
       {
+        model:   @record.class,
         context: @context,
-        object:  @record
-      }
+        record:  @record,
+        options: @options
+      }.merge(@restrictions.reflection)
     end
 
     protected
@@ -203,10 +261,11 @@ module Heimdallr
         action = :update
       end
 
-      fixtures   = @restrictions.fixtures[action]
-      validators = @restrictions.validators[action]
+      allowed_fields = @restrictions.allowed_fields[action]
+      fixtures       = @restrictions.fixtures[action]
+      validators     = @restrictions.validators[action]
 
-      @record.changed.each do |attribute|
+      @record.changed.map(&:to_sym).each do |attribute|
         value = @record.send attribute
 
         if fixtures.has_key? attribute
@@ -214,6 +273,9 @@ module Heimdallr
             raise Heimdallr::PermissionError,
                 "Attribute #{attribute} value (#{value}) is not equal to a fixture (#{fixtures[attribute]})"
           end
+        elsif !allowed_fields.include? attribute
+          raise Heimdallr::PermissionError,
+              "Attribute #{attribute} is not allowed to change"
         end
       end
 
@@ -231,6 +293,18 @@ module Heimdallr
         raise Heimdallr::InsecureOperationError,
             "Saving while omitting validation would omit security validations too"
       end
+
+      if @record.new_record?
+        unless @restrictions.can? :create
+          raise Heimdallr::InsecureOperationError,
+              "Creating was not explicitly allowed"
+        end
+      else
+        unless @restrictions.can? :update
+          raise Heimdallr::InsecureOperationError,
+              "Updating was not explicitly allowed"
+        end
+      end
     end
   end
 end

metadata

@@ -1,19 +1,20 @@
 --- !ruby/object:Gem::Specification
 name: heimdallr
 version: !ruby/object:Gem::Version
-  version: 0.0.2
-  prerelease: 
+  version: 1.0.0.RC2
+  prerelease: 6
 platform: ruby
 authors:
 - Peter Zotov
+- Boris Staal
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-06 00:00:00.000000000 Z
+date: 2012-04-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &83064660 !ruby/object:Gem::Requirement
+  requirement: &76679020 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +22,10 @@ dependencies:
         version: 3.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *83064660
+  version_requirements: *76679020
 - !ruby/object:Gem::Dependency
   name: activemodel
-  requirement: &83064350 !ruby/object:Gem::Requirement
+  requirement: &76678260 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +33,10 @@ dependencies:
         version: 3.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *83064350
+  version_requirements: *76678260
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &83064110 !ruby/object:Gem::Requirement
+  requirement: &76677800 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +44,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *83064110
+  version_requirements: *76677800
 - !ruby/object:Gem::Dependency
   name: activerecord
-  requirement: &83063840 !ruby/object:Gem::Requirement
+  requirement: &79365140 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,12 +55,13 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *83063840
+  version_requirements: *79365140
 description: ! "Heimdallr aims to provide an easy to configure and efficient object-
   and field-level access\n control solution, reusing proven patterns from gems like
   CanCan and allowing one to manage permissions in a very\n fine-grained manner."
 email:
 - whitequark@whitequark.org
+- boris@roundlake.ru
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -75,10 +77,10 @@ files:
 - heimdallr.gemspec
 - lib/heimdallr.rb
 - lib/heimdallr/evaluator.rb
+- lib/heimdallr/legacy_resource.rb
 - lib/heimdallr/model.rb
 - lib/heimdallr/proxy/collection.rb
 - lib/heimdallr/proxy/record.rb
-- lib/heimdallr/resource.rb
 - lib/heimdallr/validator.rb
 - spec/proxy_spec.rb
 - spec/spec_helper.rb
@@ -97,15 +99,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>='
+  - - ! '>'
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubyforge_project: heimdallr
-rubygems_version: 1.8.10
+rubyforge_project: 
+rubygems_version: 1.8.17
 signing_key: 
 specification_version: 3
 summary: Heimdallr is an ActiveModel extension which provides object- and field-level
   access control.
 test_files: []
-has_rdoc: