authorule 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 94b612796ca264f8a74cc1a5279093c602cffe77
+  data.tar.gz: 8753373eca10d39f80ccbfa89469d5e6b7e30e34
+SHA512:
+  metadata.gz: 90a3b01b1e02017f54ec9c3a931d0662a36b424e7f3c5c8c38f8277b2ceea8f8e646d5addad3cbf06261c095bce725302e71dcd1b204a718b57dda5a6c8858cf
+  data.tar.gz: 2ed129fc2f22109705614d3fd0f807eb79b88bb465503fd22c48751db6c1c266dc5c1291ba9fec4253b1b362c9be029a9e4285ee2e73beb0785eac275c5c85a2

data/.gitignore

@@ -0,0 +1,29 @@
+# See http://help.github.com/ignore-files/ for more about ignoring files.
+#
+# If you find yourself ignoring temporary files generated by your text editor
+# or operating system, you probably want to add a global ignore instead:
+#   git config --global core.excludesfile ~/.gitignore_global
+
+# Ignore .DS_Store
+.DS_Store
+
+# Ignore the output files.
+/pkg
+
+# Ignore bundler and database config and precompiled assets
+/.bundle
+/.env
+
+# Ignore all logfiles and tempfiles.
+/tmp
+
+# Ignore TextMate projects
+*.tmproj
+*.sublime-project
+*.sublime-workspace
+
+# Documentation files and other stuff
+.yardoc
+/doc
+/nbproject
+/coverage

data/.ruby-gemset

@@ -0,0 +1 @@
+flux

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.0.0-p247

data/.travis.yml

@@ -0,0 +1,9 @@
+script: bundle exec rake
+rvm:
+  - 1.9.2
+  - 1.9.3
+  - 2.0.0
+
+branches:
+  only:
+    - master

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+## 1.0.0
+
+* V1 Release
+
+## 0.0.2
+
+* Update in documentation
+* Bug fix in loading constants
+
+## 0.0.1
+
+* Initial extraction from Flux framework

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in authorule.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,45 @@
+PATH
+  remote: .
+  specs:
+    authorule (0.0.2)
+      activesupport (~> 3.2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (3.2.14)
+      activesupport (= 3.2.14)
+      builder (~> 3.0.0)
+    activerecord (3.2.14)
+      activemodel (= 3.2.14)
+      activesupport (= 3.2.14)
+      arel (~> 3.0.2)
+      tzinfo (~> 0.3.29)
+    activesupport (3.2.14)
+      i18n (~> 0.6, >= 0.6.4)
+      multi_json (~> 1.0)
+    arel (3.0.2)
+    builder (3.0.4)
+    diff-lcs (1.2.4)
+    i18n (0.6.5)
+    multi_json (1.7.9)
+    rake (10.1.0)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.5)
+    rspec-expectations (2.14.3)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.3)
+    tzinfo (0.3.37)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activerecord (~> 3.2)
+  authorule!
+  bundler (~> 1.3)
+  rake
+  rspec (~> 2.14)

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Joost Lubach
+
+MIT License
+
+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,123 @@
+# Authorule
+
+Rule based authorization library.
+
+[<img src="https://secure.travis-ci.org/yoazt/authorule.png?branch=master" alt="Build Status" />](http://travis-ci.org/yoazt/authorule)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'authorule'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install authorule
+
+## Usage
+
+### Write rule model
+
+Write a permission rule model. By default, `Authorule` expects this to be called `PermissionRule`. You may add any associations in the class, but this is not required by this gem.
+
+    class PermissionRule < ActiveRecord::Base
+      include Authorule::Rule
+
+      belongs_to :user
+    end
+
+Use the following migration for this class (TODO: write a generator):
+
+    class CreatePermissionRules < ActiveRecord::Migration
+      def change
+        create_table :permission_rules do |t|
+          t.boolean :allow, :default => true
+          t.string :kind, :limit => 20
+          t.string :name, :limit => 80
+          t.string :action, :limit => 20
+
+          # --> Add any other columns here.
+        end
+      end
+    end
+
+### Write permission holder
+
+Write a permission holder model. This is typically a `User` object. Include `Authorule::PermissionHolder` into this class, and call `is_permission_holder!`.
+
+    class User < ActiveRecord::Base
+      include Authorule::PermissionHolder
+
+      is_permission_holder!
+    end
+
+This creates an association and a rule base accessor. By default, it is assumed that the rule class is called `PermissionRule`.
+
+### Write a custom permission class
+
+Write a permission class. Each permission class should at a minimum:
+
+1. Register itself under a name.
+2. Provide a way to resolve any argument into a permission target.
+3. Provide a way to list all permission targets.
+
+A permission target is the object that you wish to secure using the permission. The following example is a permission that secures access to any ActiveRecord object. The target is the class (e.g. 'Allow user X to access Active Record class Y.'), but the permission can also resolve model instances.
+
+    class ResourcePermission < Authorule::Permission
+
+      # Register under name :resource.
+      register :resource
+
+      # Resolution.
+      resolve do |arg|
+        if arg.is_a?(ActiveRecord::Base)
+          arg.class
+        elsif arg.is_a?(Class) && arg < ActiveRecord::Base
+          arg
+        end
+      end
+
+      list do
+        classes = []
+        Dir[ Rails.root + 'app/models' + '*.rb' ].each do |file|
+          klass = File.basename(file, '.rb').camelize.safe_constantize
+          classes << klass if klass
+        end
+        classes
+      end
+
+    end
+
+### Checking permissions
+
+You can now give any user a set of rules, e.g.:
+
+1. Allow access to everything
+2. Deny access to ActiveRecord class 'Account'
+
+This allows the user to access all other ActiveRecord classes (and their objects).
+
+To check a permission, you can call:
+
+    User.may_access?(Account)
+
+or
+
+    User.may_access?(Account.new)
+
+(because it resolves into a class), or the equivalent
+
+    permission = Authorule.resolve(Account.new)
+    User.has_permission?(permission)
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,7 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/authorule.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'authorule/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "authorule"
+  spec.version       = Authorule::VERSION
+  spec.authors       = ["Joost Lubach"]
+  spec.email         = ["joost@yoazt.com"]
+  spec.description   = %q[Rule-based programmable permission system.]
+  spec.summary       = %q[Rule-based programmable permission system.]
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^spec/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activesupport", "~> 3.2"
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "activerecord", "~> 3.2"
+  spec.add_development_dependency "rspec", "~> 2.14"
+end

data/lib/authorule/permission.rb

@@ -0,0 +1,123 @@
+module Authorule
+
+  # A permission. This is an object that can be used to check if someone has access to a certain permissable.
+  #
+  # Note: do not confuse a permission with a {PermissionRule} or {PermissionRuleBase}. This class doesn't indicate
+  # that a user has been granted a permission. It simply encapsulates a permission query.
+  #
+  # This class should also not be confused with a {CustomPermission}, which is an application-defined custom
+  # permission.
+  #
+  # == Usage
+  #
+  #   permission = Permission.resolve(Campaign, :destroy)
+  #   @user.has_permission?(permission) # Granted that @user < UI::PermissionHolder
+  #
+  # Or even simpler:
+  #
+  #   @user.may?(:destroy, @campaign)
+  #
+  # == Object resolution
+  #
+  # Any object can be converted into a permission, if a suitable {Schema} can be found. For example, any UI resource
+  # can be resolved into a resource permission, but also any resource model class or even resource symbol. This
+  # allows for the following equivalent calls:
+  #
+  #   @user.may?(:destroy, UI.application.resources[:campaign])
+  #   @user.may?(:destroy, @campaign)
+  #   @user.may?(:destroy, Campaign)
+  #   @user.may?(:destroy, :campaign)
+  #
+  # The UI library defines a few schemas, for example one for resource permissions, and one for UI space permissions.
+  # There is also a custom permission schema - allowing the application designer to define additional permissions.
+  # These can be referred to throughout the UI library.
+  #
+  # @see PermissionHolder
+  # @see RuleBase
+  # @see Rule
+  class Permission
+
+    ######
+    # Initialization
+
+      # Initializes a new permission.
+      #
+      # @param object
+      #    The object of the permission.
+      # @param [Symbol|nil] action
+      #   The action the user wishes to perform.
+      def initialize(object, action = nil)
+        @object = object
+        @action = action.try(:to_sym)
+      end
+
+    ######
+    # Attributes
+
+      # @!attribute [r] object
+      # @return [Symbol] The object of the permission.
+      attr_reader :object
+
+      # @!attribute [r] action
+      # @return [Symbol|nil] The action the user wishes to perform.
+      attr_reader :action
+
+      # @!attribute [r] kind
+      # @return [Symbol] The kind of permission. This is delegated to the current class.
+      def kind
+        self.class.kind
+      end
+
+      # @!attribute [r] name
+      # @return [String] The name of the permission. This is delegated to {#object}.
+      def name
+        object.name
+      end
+
+      # @!attribute [r] available_actions
+      # @return [Array] The available actions for the permission.
+      def available_actions
+        []
+      end
+
+    ######
+    # Dependencies
+
+      # Retrieves an array of permissions consisting of dependencies and the permission itself.
+      def with_dependencies
+        dependencies + [ self ]
+      end
+
+      # Resolves dependencies for this permission. To be implemented by subclasses.
+      def dependencies
+        []
+      end
+
+    ######
+    # Registration & metadata
+
+      class << self
+
+        attr_reader :kind, :resolve_block, :list_block
+
+        # Registers a permission class under a specific kind.
+        def register(kind)
+          Authorule.register kind, self
+          @kind = kind
+        end
+
+        # Defines a block that resolves any argument into a suitable permission target.
+        def resolve(&block)
+          @resolve_block = block
+        end
+
+        # Defines a block that lists all suitable permission targets in the application.
+        def list(&block)
+          @list_block = block
+        end
+
+      end
+
+  end
+
+end

data/lib/authorule/permission_accessors.rb

@@ -0,0 +1,47 @@
+module Authorule
+
+  # Provides methods 'may?', 'may_access?' and their negative counterparts. You must make sure
+  # to implement method 'has_permission?' in your class.
+  module PermissionAccessors
+
+    # Determines whether a holder in this group may perform the specified action on the specified target.
+    #
+    # @param [#to_s] action
+    #   The action to perform. The available actions differ per permissions. The full list can be found
+    #   in {UI::Permission}.
+    # @param target
+    #   The target the holder wishes to operate on. This target may be any object and is passed to the UI
+    #   permission checker as is, which will convert it into a permission path.
+    def may?(action, target)
+      permission = Authorule.resolve(target, action)
+      unless permission.available_actions.try(:include?, action)
+        raise ArgumentError, "action :#{action} not available for permission of kind :#{permission.class.kind}"
+      end
+
+      has_permission? permission
+    end
+
+    # Checks a permission without querying a specific action.
+    # @see #may?
+    def may_access?(target)
+      permission = Authorule.resolve(target)
+      has_permission? permission
+    end
+
+    # Determines whether a holder may not perform the specified action on the specified target.
+    # @see #may?
+    def may_not?(action, target)
+      !may?(action, target)
+    end
+
+    # Determines whether a holder may not access the specified target.
+    # @see #may_not?
+    # @see #may?
+    def may_not_access?(target)
+      !may_access?(target)
+    end
+
+
+
+  end
+end

data/lib/authorule/permission_holder.rb

@@ -0,0 +1,55 @@
+module Authorule
+
+  # Makes any ActiveModel/ActiveRecord-like class a UI permission holder.
+  #
+  # == Usage
+  #
+  #   class User
+  #     include Authorule::PermissionHolder
+  #     is_permission_holder!
+  #   end
+  #
+  # * A (has many) +permission_rules+ association is added to the model (though the
+  #   name may be changed in the {.is_permission_holder!} method).
+  # * A {#may?} and {#may_not?} method is added.
+  module PermissionHolder
+    extend ActiveSupport::Concern
+
+    include PermissionAccessors
+
+    module ClassMethods
+
+      # Marks this class as a permission holder with the given options.
+      #
+      # @option options [#to_sym] association_name (:permission_rules)
+      #   The name of the permission rules association.
+      def is_permission_holder!(options = {})
+        association_name = options[:association_name] || :permission_rules
+
+        class_eval <<-RUBY, __FILE__, __LINE__+1
+          has_many :#{association_name}
+
+          def permission_rule_base(reload = false)
+            @permission_rule_base = nil if reload
+            @permission_rule_base ||= RuleBase.new(#{association_name}(true))
+          end
+        RUBY
+      end
+
+    end
+
+    ######
+    # has_permission?
+
+      # Determines whether this holder has the given permission by running it through his rule base.
+      def has_permission?(permission)
+        unless respond_to?(:permission_rule_base)
+          raise "class not set up as permission holder, call is_permission_holder! first"
+        end
+
+        permission_rule_base.run permission
+      end
+
+  end
+
+end

data/lib/authorule/railtie.rb

@@ -0,0 +1,21 @@
+require File.expand_path('..', __FILE__)
+
+module Authorule
+
+  class Railtie < Rails::Railtie
+
+    generators do
+      Dir[ File.expand_path('../generators/*/*_generator.rb', __FILE__) ].each do |path|
+        require path
+      end
+    end
+
+    rake_tasks do
+      Dir[ File.expand_path('../tasks/**/*.rake', __FILE__) ].each do |path|
+        load path
+      end
+    end
+
+  end
+
+end

data/lib/authorule/rule.rb

@@ -0,0 +1,111 @@
+module Authorule
+
+  # A permission rule. Each rule allows or denies the permission holder one permission.
+  #
+  # == Usage
+  #
+  # Create a model class, and include this mixin into it, e.g.
+  #
+  #   class PermissionRule < ActiveRecord::Base
+  #     include Authorule::Rule
+  #
+  #     belongs_to :user
+  #   end
+  #
+  # @see RuleBase
+  module Rule
+    extend ActiveSupport::Concern
+
+    ######
+    # Attributes & validations
+
+      included do
+        validates_inclusion_of :allow, :in => [ true, false ]
+        validates_presence_of :kind, :name
+
+        validates_length_of :kind, :maximum => 20
+        validates_length_of :name, :maximum => 80
+        validates_length_of :action, :maximum => 20, :allow_blank => true
+
+        # Make sure to coerce a blank value for action into an absolute nil.
+        before_validation { self.action = nil if self.action.blank? }
+      end
+
+    ######
+    # Rule creation accessors
+
+      # Builds an allow rule for the given kind and name.
+      def self.allow(kind, name, attributes = {})
+        new attributes.merge(:kind => kind, :name => name, :allow => true)
+      end
+
+      # Creates an allow rule for the given kind and name.
+      def self.allow!(kind, name, attributes = {})
+        allow(kind, name, attributes).save
+      end
+
+      # Builds a deny rule for the given kind and name.
+      def self.deny(kind, name, attributes = {})
+        new attributes.merge(:kind => kind, :name => name, :allow => false)
+      end
+
+      # Creates a deny rule for the given kind and name.
+      def self.deny!(kind, name, attributes = {})
+        deny(kind, name, attributes).save
+      end
+
+      # Builds an 'allow all' rule.
+      #
+      # == Examples
+      #
+      #   Rule.allow_all              # => kind 'all', name 'all'
+      #   Rule.allow_all(:resource)   # => kind 'resource', name 'all'
+      def self.allow_all(kind = :all, attributes = {})
+        new attributes.merge(:kind => kind, :name => 'all', :allow => true)
+      end
+
+      # Creates an 'allow all' rule.
+      # @see .allow_all
+      def self.allow_all!(kind = :all, attributes = {})
+        allow_all(kind, attributes).save
+      end
+
+      # Creates a 'deny all' rule.
+      #
+      # == Examples
+      #
+      #   Rule.deny_all              # => kind 'all', name 'all'
+      #   Rule.deny_all(:resource)   # => kind 'resource', name 'all'
+      def self.deny_all(kind = :all, attributes = {})
+        new attributes.merge(:kind => kind, :name => 'all', :allow => false)
+      end
+
+      # Creates an 'deny all' rule.
+      # @see .deny_all
+      def self.deny_all!(kind = :all, attributes = {})
+        allow_all(kind, attributes).save
+      end
+
+    ######
+    # Rule key
+
+      # @!attribute [r] key
+      # @return [String] A unique key identifying this rule.
+      def key
+        if kind == 'all'
+          'all'
+        else
+          [ kind, name, action ].compact.join(':')
+        end
+      end
+
+    ######
+    # Misc
+
+      def to_display
+        key
+      end
+
+  end
+
+end