heimdallr 0.0.1 → 0.0.2

data/.gitignore

@@ -1,4 +1,6 @@
 *.gem
 .bundle
+.yardoc
 Gemfile.lock
 pkg/*
+doc/*

data/.yardopts

@@ -0,0 +1 @@
+--no-private --protected -r README.yard.md --exclude README.md - LICENSE

data/LICENSE

@@ -0,0 +1,19 @@
+    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.

data/README.md

@@ -0,0 +1,128 @@
+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
+      can :fetch
+      can [:view, :create, :update, :destroy]
+    else
+      # Other users can view only non-classified articles...
+      can :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, :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"]
+secure.find(1).secrecy_level
+# => nil
+
+# Everything should be permitted explicitly:
+secure.first.delete
+# ! Heimdallr::PermissionError is raised
+
+# 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"
+# ! ActiveRecord::RecordInvalid 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](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.
+
+REST interface
+--------------
+
+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.
+
+The interface is described in documentation for [Heimdallr::Resource](http://rubydoc.info/gems/heimdallr/0.0.2/Heimdallr/Resource).
+
+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.

data/README.yard.md

@@ -0,0 +1,128 @@
+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
+      can :fetch
+      can [:view, :create, :update, :destroy]
+    else
+      # Other users can view only non-classified articles...
+      can :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, :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"]
+secure.find(1).secrecy_level
+# => nil
+
+# Everything should be permitted explicitly:
+secure.first.delete
+# ! Heimdallr::PermissionError is raised
+
+# 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"
+# ! ActiveRecord::RecordInvalid 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}.
+
+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
+--------------
+
+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.
+
+The interface is described in documentation for {Heimdallr::Resource}.
+
+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.

data/Rakefile

@@ -1 +1,21 @@
 require "bundler/gem_tasks"
+
+Dir.chdir File.dirname(__FILE__)
+
+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

data/heimdallr.gemspec

@@ -1,16 +1,15 @@
 # -*- encoding: utf-8 -*-
 $:.push File.expand_path("../lib", __FILE__)
-require "heimdallr/version"
 
 Gem::Specification.new do |s|
   s.name        = "heimdallr"
-  s.version     = Heimdallr::VERSION
+  s.version     = "0.0.2"
   s.authors     = ["Peter Zotov"]
   s.email       = ["whitequark@whitequark.org"]
   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 control permissions in a very
+ 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"

data/lib/heimdallr.rb

@@ -3,7 +3,44 @@ require "active_model"
 
 require "heimdallr/version"
 
+require "heimdallr/proxy/collection"
+require "heimdallr/proxy/record"
+require "heimdallr/validator"
 require "heimdallr/evaluator"
-require "heimdallr/proxy"
 require "heimdallr/model"
-require "heimdallr/resource"
+require "heimdallr/resource"
+
+# See {file:README.yard}.
+module Heimdallr
+  class << self
+    # Allow implicit insecure association access. Consider this code:
+    #
+    #     class User < ActiveRecord::Base
+    #       include Heimdallr::Model
+    #
+    #       has_many :articles
+    #     end
+    #
+    #     class Article < ActiveRecord::Base
+    #       # No Heimdallr::Model!
+    #     end
+    #
+    # If the +allow_insecure_associations+ setting is +false+ (the default),
+    # then +user.restrict(context).articles+ fetch would cause an
+    # {InsecureOperationError}. This may be undesirable in some environments;
+    # setting +allow_insecure_associations+ to +true+ will prevent the error
+    # from being raised.
+    #
+    # @return [Boolean]
+    attr_accessor :allow_insecure_associations
+    self.allow_insecure_associations = false
+  end
+
+  # {PermissionError} is raised when a security policy prevents
+  # a called operation from being executed.
+  class PermissionError < StandardError; end
+
+  # {InsecureOperationError} is raised when a potentially unsafe
+  # operation is about to be executed.
+  class InsecureOperationError < StandardError; end
+end

data/lib/heimdallr/evaluator.rb

@@ -1,67 +1,149 @@
 module Heimdallr
+  # Evaluator is a DSL for managing permissions on records with the field granularity.
+  # It works by evaluating a block of code within a given <em>security context</em>.
+  #
+  # The default resolution is to forbid everything--that is, Heimdallr security policy
+  # is whitelisting safe actions, not blacklisting unsafe ones. This is by design
+  # and is not going to change.
+  #
+  # The DSL consists of three functions: {#scope}, {#can} and {#cannot}.
   class Evaluator
-    attr_reader :whitelist, :validations
+    attr_reader :allowed_fields, :fixtures, :validators
 
-    def initialize(model_class, &block)
+    # Create a new Evaluator for the ActiveModel-descending 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
 
-      @whitelist = @validations = nil
-      @last_context = nil
+      @scopes         = {}
+      @allowed_fields = {}
+      @validations    = {}
+      @fixtures       = {}
     end
 
-    def evaluate(context)
-      if context != @last_context
-        @whitelist   = Hash.new { [] }
-        @validations = Hash.new { [] }
-
-        instance_exec context, &block
-
-        @whitelist.freeze
-        @validations.freeze
+    # @group DSL
+
+    # Define a scope. A special +:fetch+ scope is applied to any other scope
+    # automatically.
+    #
+    # @overload scope(name, block)
+    #   This form accepts an explicit lambda.
+    #
+    #   @example
+    #       scope :fetch, -> { where(:protected => false) }
+    #
+    # @overload scope(name)
+    #   This form accepts an implicit lambda.
+    #
+    #   @example
+    #       scope :fetch do
+    #         if user.manager?
+    #           scoped
+    #         else
+    #           where(:invisible => false)
+    #         end
+    #       end
+    def scope(name, explicit_block, &implicit_block)
+      @scopes[name] = explicit_block || implicit_block
+    end
 
-        @last_context = context
+    # Define allowed operations for action(s).
+    #
+    # The +fields+ parameter accepts both Arrays and Hashes.
+    # * If an +Array+ is passed, then all fields present in the array are whitelised.
+    # * If a +Hash+ is passed, then all fields present as hash keys are whitelisted, and:
+    #   1. If a corresponding value is a +Hash+, it will be processed as a security
+    #      validator. Security validators make records invalid when they are saved through
+    #      a {Proxy::Record}.
+    #   2. If the corresponding value is any other object, it will be added as a security
+    #      fixture. Fixtures are merged when objects are created through restricted scopes,
+    #      and cause exceptions to be raised when a record is saved, even through the +#save+
+    #      method.
+    #
+    # @example Array of fields
+    #   can :view, [:title, :content]
+    #
+    # @example Fixtures
+    #   can :create, { owner: current_user }
+    #
+    # @example Validations
+    #   can [:create, :update], { priority: { inclusion: 1..10 } }
+    #
+    # @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|
+        case fields
+        when Hash # a list of validations
+          @allowed_fields[action] += fields.keys
+          @validations[action]    += create_validators(fields)
+          @fixtures[action].merge extract_fixtures(fields)
+
+        else # an array or a field name
+          @allowed_fields[action] += Array(fields)
+        end
       end
-
-      self
     end
 
-    def validate(action, record)
-      @validations[action].each do |validator|
-        validator.validate(record)
+    # Revoke a permission on fields.
+    #
+    # @todo Revoke validating restrictions.
+    # @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
+        @fixtures.delete_at *fields
       end
     end
 
-    def can(actions, fields=@model_class.attribute_names)
-      actions = Array(actions)
-
-      case fields
-      when Hash # a list of validations
-        actions.each do |action|
-          @whitelist[action]   += fields.keys
-          @validations[action] += make_validators(fields)
-        end
-
-      else # an array or a field name
-        actions.each do |action|
-          @whitelist[action] += Array(fields)
-        end
+    # @endgroup
+
+    # Request a scope.
+    #
+    # @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])
+      else
+        basic_scope.instance_exec(&@scopes[name])
       end
     end
 
-    def cannot(actions, fields)
-      actions = Array(actions)
+    # Compute the restrictions for a given +context+. Invokes a +block+ passed to the
+    # +initialize+ once.
+    def evaluate(context)
+      if context != @last_context
+        @scopes         = {}
+        @allowed_fields = Hash.new { [] }
+        @validators     = Hash.new { [] }
+        @fixtures       = Hash.new { [] }
+
+        instance_exec context, &block
 
-      actions.each do |action|
-        @whitelist[action] -= fields
+        [@scopes, @allowed_fields, @validators, @fixtures].
+              map(&:freeze)
+
+        @last_context = context
       end
+
+      self
     end
 
     protected
 
-    def make_validators(fields)
-      validators = []
+    # Create validators for +fields+ in +ActiveModel::Validations+-like way.
+    #
+    # @return [Array<ActiveModel::Validator>]
+    def create_validators(fields)
+      validators = {}
 
       fields.each do |attribute, validations|
+        next unless validations.is_a? Hash
+
         validations.each do |key, options|
           key = "#{key.to_s.camelize}Validator"
 
@@ -71,14 +153,30 @@ module Heimdallr
             raise ArgumentError, "Unknown validator: '#{key}'"
           end
 
-          validators << validator.new(_parse_validates_options(options).merge(:attributes => [ attribute ]))
+          validators[attribute] = validator.new(_parse_validates_options(options).merge(:attributes => [ attribute ]))
         end
       end
 
       validators
     end
 
-    def _parse_validates_options(options) #:nodoc:
+    # Collects fixtures from the +fields+ definition.
+    def extract_fixtures(fields)
+      fixtures = {}
+
+      fields.each do |attribute, options|
+        next if options.is_a? Hash
+
+        fixtures[attribute] = options
+      end
+
+      fixtures
+    end
+
+    private
+
+    # Monkey-copied from ActiveRecord.
+    def _parse_validates_options(options)
       case options
       when TrueClass
         {}