heimdallr 1.0.0.RC2 → 1.0.0

data/.gitignore

@@ -3,4 +3,5 @@
 .yardoc
 Gemfile.lock
 pkg/*
-doc/*
+doc/*
+tmp/debug.log

data/README.md

@@ -16,24 +16,33 @@ class Article < ActiveRecord::Base
 
   belongs_to :owner, :class_name => 'User'
 
-  restrict do |user|
-    if user.admin? || user == self.owner
+  restrict do |user, record|
+    if user.admin?
       # Administrator or owner can do everything
       scope :fetch
-      scope :destroy
+      scope :delete
       can [:view, :create, :update]
     else
-      # Other users can view only non-classified articles...
-      scope :fetch, -> { where('secrecy_level < ?', 5) }
-
-      # ... and see all fields except the actual security level...
-      can    :view
-      cannot :view, [:secrecy_level]
+      # Other users can view only their own or non-classified articles...
+      scope :fetch,  -> { where('owner_id = ? or secrecy_level < ?', user.id, 5) }
+      scope :delete, -> { where('owner_id = ?', user.id) }
+
+      # ... and see all fields except the actual security level
+      # (through owners can see everything)...
+      if record.try(:owner) == user
+        can :view
+        can :update, {
+          secrecy_level: { inclusion: { in: 0..4 } }
+        }
+      else
+        can    :view
+        cannot :view, [:secrecy_level]
+      end
 
       # ... and can create them with certain restrictions.
       can :create, %w(content)
-      can [:create, :update], {
-        owner:         user,
+      can :create, {
+        owner_id:      user.id,
         secrecy_level: { inclusion: { in: 0..4 } }
       }
     end
@@ -85,7 +94,7 @@ secure.find 2
 # -- No, it is not.
 ```
 
-The DSL is described in documentation for [Heimdallr::Model](http://rubydoc.info/gems/heimdallr/1.0.0.RC2/Heimdallr/Model).
+The DSL is described in documentation for [Heimdallr::Model](http://rubydoc.info/gems/heimdallr/master/Heimdallr/Model).
 
 Ideology
 --------
@@ -94,8 +103,18 @@ Heimdallr aims to make security explicit, but nevertheless convenient. It does n
 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.
 
-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).
+Heimdallr has two restrictions strategies: explicit and implicit. By default it will use explicit strategy
+that means it will raise an exception for every insecure request. Calling `.implicit` will give you a copy
+of proxy object switched to another strategy. With that it will silently return nil for every attribute
+that is inaccessible.
+
+Typical cases
+-------------
+
+While working with MVC you'll mostly use Heimdallr-wrapped models inside your controllers and views. To
+protect your controllers using DSL from the model you can use [Heimdallr::Resource](http://github.com/roundlake/heimdallr-resource) extension gem.
+
+To facilitate views you can use `implicit` strategy which is described above.
 
 Compatibility
 -------------
@@ -107,6 +126,8 @@ Licensing
 
     Copyright (C) 2012  Peter Zotov <whitequark@whitequark.org>
 
+    Funded by Round Lake.
+
     Permission is hereby granted, free of charge, to any person obtaining a copy of
     this software and associated documentation files (the "Software"), to deal in
     the Software without restriction, including without limitation the rights to

data/Rakefile

@@ -1,21 +1,7 @@
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
-Dir.chdir File.dirname(__FILE__)
+RSpec::Core::RakeTask.new(:spec)
 
-gemspec = Bundler.load_gemspec Dir["{,*}.gemspec"].first
-
-task :release => :prepare_for_release
-
-task :prepare_for_release do
-  readme = File.read('README.yard.md')
-  readme.gsub! /{([[:alnum:]:]+)}/i do |match|
-    %Q|[#{$1}](http://rubydoc.info/gems/#{gemspec.name}/#{gemspec.version}/#{$1.gsub '::', '/'})|
-  end
-
-  File.open('README.md', 'w') do |f|
-    f.write readme
-  end
-
-  %x|git add README.md|
-  #%x|git commit -m "Bump version to #{gemspec.version}."|
-end
+desc "Default: run the unit tests."
+task :default => [:spec]

data/heimdallr.gemspec

@@ -3,7 +3,7 @@ $:.push File.expand_path("../lib", __FILE__)
 
 Gem::Specification.new do |s|
   s.name        = "heimdallr"
-  s.version     = "1.0.0.RC2"
+  s.version     = "1.0.0"
   s.authors     = ["Peter Zotov", "Boris Staal"]
   s.email       = ["whitequark@whitequark.org", "boris@roundlake.ru"]
   s.homepage    = "http://github.com/roundlake/heimdallr"

data/lib/heimdallr/evaluator.rb

@@ -28,8 +28,9 @@ module Heimdallr
     # Define a scope. A special +:fetch+ scope is applied to any other scope
     # automatically.
     #
-    # @overload scope(name, block)
-    #   This form accepts an explicit lambda.
+    # @overload scope(name, block=nil)
+    #   This form accepts an explicit lambda. If omitted, a scope will be
+    #   defined to include all possible records.
     #
     #   @example
     #       scope :fetch, -> { where(:protected => false) }
@@ -45,8 +46,12 @@ module Heimdallr
     #           where(:invisible => false)
     #         end
     #       end
-    def scope(name, explicit_block, &implicit_block)
-      @scopes[name] = explicit_block || implicit_block
+    def scope(name, explicit_block=nil, &implicit_block)
+      unless [:fetch, :delete].include?(name)
+        raise "There is no such scope as #{name}"
+      end
+
+      @scopes[name] = explicit_block || implicit_block || -> { scoped }
     end
 
     # Define allowed operations for action(s).
@@ -98,7 +103,7 @@ module Heimdallr
     def cannot(actions, fields)
       Array(actions).map(&:to_sym).each do |action|
         @allowed_fields[action] -= fields.map(&:to_sym)
-        @fixtures.delete_at *fields
+        fields.each { |field| @fixtures.delete field }
       end
     end
 
@@ -140,12 +145,12 @@ module Heimdallr
       }
     end
 
-    # Compute the restrictions for a given +context+. Invokes a +block+ passed to the
-    # +initialize+ once.
+    # Compute the restrictions for a given +context+ and possibly a specific +record+.
+    # 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
+    def evaluate(context, record=nil)
+      if [context, record] != @last_context
         @scopes         = {}
         @allowed_fields = Hash.new { [] }
         @validators     = Hash.new { [] }
@@ -153,7 +158,7 @@ module Heimdallr
 
         @allowed_fields[:view] += [ :id ]
 
-        instance_exec context, &@block
+        instance_exec context, record, &@block
 
         unless @scopes[:fetch]
           raise RuntimeError, "A :fetch scope must be defined"
@@ -166,7 +171,7 @@ module Heimdallr
         [@scopes, @allowed_fields, @validators, @fixtures].
               map(&:freeze)
 
-        @last_context = context
+        @last_context = [context, record]
       end
 
       self

data/lib/heimdallr/model.rb

@@ -39,11 +39,11 @@ module Heimdallr
         end
       end
 
-      # Evaluate the restrictions for a given +context+.
+      # Evaluate the restrictions for a given +context+ and +record+.
       #
       # @return [Evaluator]
-      def restrictions(context)
-        @restrictions.evaluate(context)
+      def restrictions(context, record=nil)
+        @restrictions.evaluate(context, record)
       end
 
       # @api private

data/lib/heimdallr/proxy/record.rb

@@ -18,7 +18,7 @@ module Heimdallr
     def initialize(context, record, options={})
       @context, @record, @options = context, record, options
 
-      @restrictions = @record.class.restrictions(context)
+      @restrictions = @record.class.restrictions(context, record)
     end
 
     # @method decrement(field, by=1)
@@ -105,8 +105,10 @@ module Heimdallr
       class_eval(<<-EOM, __FILE__, __LINE__)
       def #{method}
         scope = @restrictions.request_scope(:delete)
-        if scope.where({ @record.class.primary_key => @record.to_key }).count != 0
+        if scope.where({ @record.class.primary_key => @record.to_key }).any?
           @record.#{method}
+        else
+          raise PermissionError, "Deletion is forbidden"
         end
       end
       EOM
@@ -128,6 +130,10 @@ module Heimdallr
     # @macro delegate
     delegate :assign_attributes, :to => :@record
 
+    # @method attributes=
+    # @macro delegate
+    delegate :attributes=, :to => :@record
+
     # Class name of the underlying model.
     # @return [String]
     def class_name
@@ -246,6 +252,15 @@ module Heimdallr
       }.merge(@restrictions.reflection)
     end
 
+    def modifiable?
+      @restrictions.can? :update
+    end
+
+    def destroyable?
+      scope = @restrictions.request_scope(:delete)
+      scope.where({ @record.class.primary_key => @record.to_key }).any?
+    end
+
     protected
 
     # Raises an exception if any of the changed attributes are not valid

data/spec/proxy_spec.rb

@@ -1,5 +1,125 @@
 require 'spec_helper'
 
+class User < ActiveRecord::Base; end
+
+class Article < ActiveRecord::Base
+  include Heimdallr::Model
+
+  belongs_to :owner, :class_name => 'User'
+
+  restrict do |user, record|
+    if user.admin?
+      # Administrator or owner can do everything
+      scope :fetch
+      scope :delete
+      can [:view, :create, :update]
+    else
+      # Other users can view only their own or non-classified articles...
+      scope :fetch,  -> { where('owner_id = ? or secrecy_level < ?', user.id, 5) }
+      scope :delete, -> { where('owner_id = ?', user.id) }
+
+      # ... and see all fields except the actual security level
+      # (through owners can see everything)...
+      if record.try(:owner) == user
+        can :view
+        can :update, {
+          secrecy_level: { inclusion: { in: 0..4 } }
+        }
+      else
+        can    :view
+        cannot :view, [:secrecy_level]
+      end
+
+      # ... and can create them with certain restrictions.
+      can :create, %w(content)
+      can :create, {
+        owner_id:      user.id,
+        secrecy_level: { inclusion: { in: 0..4 } }
+      }
+    end
+  end
+end
+
 describe Heimdallr::Proxy do
-  pending "write it"
+  before(:all) do
+    @john = User.create! :admin => false
+    Article.create! :owner_id => @john.id, :content => 'test', :secrecy_level => 10
+    Article.create! :owner_id => @john.id, :content => 'test', :secrecy_level => 3
+  end
+
+  before(:each) do
+    @admin  = User.new :admin => true
+    @looser = User.new :admin => false
+  end
+
+  it "should apply restrictions" do
+    proxy = Article.restrict(@admin)
+    proxy.should be_a_kind_of Heimdallr::Proxy::Collection
+
+    proxy = Article.restrict(@looser)
+    proxy.should be_a_kind_of Heimdallr::Proxy::Collection
+  end
+
+  it "should handle fetch scope" do
+    Article.restrict(@admin).all.count.should == 2
+    Article.restrict(@looser).all.count.should == 1
+    Article.restrict(@john).all.count.should == 2
+  end
+
+  it "should handle destroy scope" do
+    article = Article.create! :owner_id => @john.id, :content => 'test', :secrecy_level => 0
+    expect { article.restrict(@looser).destroy }.should raise_error
+    expect { article.restrict(@john).destroy }.should_not raise_error
+
+    article = Article.create! :owner_id => @john.id, :content => 'test', :secrecy_level => 0
+    expect { article.restrict(@admin).destroy }.should_not raise_error
+  end
+
+  it "should handle list of fields to view" do
+    article = Article.create! :owner_id => @john.id, :content => 'test', :secrecy_level => 0
+    expect { article.restrict(@looser).secrecy_level }.should raise_error
+    expect { article.restrict(@admin).secrecy_level }.should_not raise_error
+    expect { article.restrict(@john).secrecy_level }.should_not raise_error
+    article.restrict(@looser).content.should == 'test'
+  end
+
+  it "should handle entities creation" do
+    expect { Article.restrict(@looser).create! :content => 'test', :secrecy_level => 10 }.should raise_error
+
+    article = Article.restrict(@john).create! :content => 'test', :secrecy_level => 3
+    article.owner_id.should == @john.id
+  end
+
+  it "should handle entities update" do
+    article = Article.create! :owner_id => @john.id, :content => 'test', :secrecy_level => 10
+    expect {
+      article.restrict(@john).update_attributes! :secrecy_level => 8
+    }.should raise_error
+    expect {
+      article.restrict(@looser).update_attributes! :secrecy_level => 3
+    }.should raise_error
+    expect {
+      article.restrict(@admin).update_attributes! :secrecy_level => 10
+    }.should_not raise_error
+  end
+
+  it "should handle implicit strategy" do
+    article = Article.create! :owner_id => @john.id, :content => 'test', :secrecy_level => 4
+    expect { article.restrict(@looser).secrecy_level }.should raise_error
+    article.restrict(@looser).implicit.secrecy_level.should == nil
+  end
+
+  it "should answer if object is modifiable" do
+    article = Article.create! :owner_id => @john.id, :content => 'test', :secrecy_level => 4
+    article.restrict(@john).modifiable?.should == true
+    article.restrict(@admin).modifiable?.should == true
+    article.restrict(@looser).modifiable?.should == false
+  end
+
+  it "should answer if object is destroyable" do
+    article = Article.create! :owner_id => @john.id, :content => 'test', :secrecy_level => 4
+    article.restrict(@john).destroyable?.should == true
+    article.restrict(@admin).destroyable?.should == true
+    article.restrict(@looser).destroyable?.should == false
+  end
 end

data/spec/spec_helper.rb

@@ -1,5 +1,22 @@
 require "heimdallr"
+require "active_record"
+require "sqlite3"
+require "logger"
+require "uri"
 
-RSpec.configure do |config|
-  # See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+ROOT = File.join(File.dirname(__FILE__), '..')
+
+ActiveRecord::Base.logger = Logger.new('tmp/debug.log')
+ActiveRecord::Base.configurations = YAML::load(IO.read('tmp/database.yml'))
+ActiveRecord::Base.establish_connection('test')
+
+ActiveRecord::Base.connection.create_table(:users) do |t|
+  t.boolean     :admin
 end
+
+ActiveRecord::Base.connection.create_table(:articles) do |t|
+  t.belongs_to  :owner
+  t.text        :content
+  t.integer     :secrecy_level
+  t.timestamps
+end

data/tmp/database.yml

@@ -0,0 +1,5 @@
+test:
+   adapter: sqlite3
+   database: ":memory:"
+   pool: 5
+   timeout: 5000

metadata

@@ -1,8 +1,8 @@
 --- !ruby/object:Gem::Specification
 name: heimdallr
 version: !ruby/object:Gem::Version
-  version: 1.0.0.RC2
-  prerelease: 6
+  version: 1.0.0
+  prerelease: 
 platform: ruby
 authors:
 - Peter Zotov
@@ -10,11 +10,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-02 00:00:00.000000000 Z
+date: 2012-04-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &76679020 !ruby/object:Gem::Requirement
+  requirement: &70194887048460 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -22,10 +22,10 @@ dependencies:
         version: 3.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *76679020
+  version_requirements: *70194887048460
 - !ruby/object:Gem::Dependency
   name: activemodel
-  requirement: &76678260 !ruby/object:Gem::Requirement
+  requirement: &70194887047820 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -33,10 +33,10 @@ dependencies:
         version: 3.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *76678260
+  version_requirements: *70194887047820
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &76677800 !ruby/object:Gem::Requirement
+  requirement: &70194887047340 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -44,10 +44,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *76677800
+  version_requirements: *70194887047340
 - !ruby/object:Gem::Dependency
   name: activerecord
-  requirement: &79365140 !ruby/object:Gem::Requirement
+  requirement: &70194887039320 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -55,7 +55,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *79365140
+  version_requirements: *70194887039320
 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."
@@ -72,7 +72,6 @@ files:
 - Gemfile
 - LICENSE
 - README.md
-- README.yard.md
 - Rakefile
 - heimdallr.gemspec
 - lib/heimdallr.rb
@@ -84,6 +83,8 @@ files:
 - lib/heimdallr/validator.rb
 - spec/proxy_spec.rb
 - spec/spec_helper.rb
+- tmp/.gitkeep
+- tmp/database.yml
 homepage: http://github.com/roundlake/heimdallr
 licenses: []
 post_install_message: 
@@ -99,14 +100,16 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>'
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.17
+rubygems_version: 1.8.15
 signing_key: 
 specification_version: 3
 summary: Heimdallr is an ActiveModel extension which provides object- and field-level
   access control.
-test_files: []
+test_files:
+- spec/proxy_spec.rb
+- spec/spec_helper.rb

data/README.yard.md

@@ -1,126 +0,0 @@
-Heimdallr
-=========
-
-Heimdallr is a gem for managing security restrictions for ActiveRecord objects on field level; think
-of it as a supercharged [CanCan](https://github.com/ryanb/cancan). Heimdallr favors whitelisting over blacklisting,
-convention over configuration and is duck-type compatible with most of existing code.
-
-``` ruby
-# Define a typical set of models.
-class User < ActiveRecord::Base
-  has_many :articles
-end
-
-class Article < ActiveRecord::Base
-  include Heimdallr::Model
-
-  belongs_to :owner, :class_name => 'User'
-
-  restrict do |user|
-    if user.admin? || user == self.owner
-      # Administrator or owner can do everything
-      scope :fetch
-      scope :destroy
-      can [:view, :create, :update]
-    else
-      # Other users can view only non-classified articles...
-      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 } }
-      }
-    end
-  end
-end
-
-# Create some fictional data.
-admin   = User.create admin: true
-johndoe = User.create admin: false
-
-Article.create id: 1, owner: admin,   content: "Nothing happens",  secrecy_level: 0
-Article.create id: 2, owner: admin,   content: "This is a secret", secrecy_level: 10
-Article.create id: 3, owner: johndoe, content: "Hello World"
-
-# Get a restricted scope for the user.
-secure = Article.restrict(johndoe)
-
-# Use any ARel methods:
-secure.pluck(:content)
-# => ["Nothing happens", "Hello World"]
-
-# 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"
-# => Article(id: 4, owner: johndoe, content: "My second article", security_level: 0)
-
-# ... and cannot be changed:
-secure.create! owner: admin, content: "I'm a haxx0r"
-# ! Heimdallr::PermissionError is raised
-
-# You can use any valid ActiveRecord validators, too:
-secure.create! content: "Top Secret", secrecy_level: 10
-# ! ActiveRecord::RecordInvalid is raised
-
-# John Doe would not see what he is not permitted to, ever:
-# -- I know that you have this classified material! It's in folder #2.
-secure.find 2
-# ! ActiveRecord::RecordNotFound is raised
-# -- No, it is not.
-```
-
-The DSL is described in documentation for {Heimdallr::Model}.
-
-Ideology
---------
-
-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.
-
-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
--------------
-
-Ruby 1.8 and ActiveRecord versions prior to 3.0 are not supported.
-
-Licensing
----------
-
-    Copyright (C) 2012  Peter Zotov <whitequark@whitequark.org>
-
-    Permission is hereby granted, free of charge, to any person obtaining a copy of
-    this software and associated documentation files (the "Software"), to deal in
-    the Software without restriction, including without limitation the rights to
-    use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
-    of the Software, and to permit persons to whom the Software is furnished to do
-    so, subject to the following conditions:
-
-    The above copyright notice and this permission notice shall be included in all
-    copies or substantial portions of the Software.
-
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-    SOFTWARE.