allowy 0.1.0

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+*.swp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--tag @focus

data/Gemfile

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

data/Guardfile

@@ -0,0 +1,13 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'rspec', :version => 2 do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+
+  watch(%r{^spec/support/(.+)\.rb$})                  { "spec" }
+  
+  callback([:start_begin, :reload_begin, :run_all_begin, :run_on_change_begin]) { system "clear" }
+end
+

data/README.md

@@ -0,0 +1,202 @@
+# Allowy - the simple authorization for Ruby (and/or Rails)
+
+Allowy is the authorization library that doesn't enforce tight DSL on you.
+It is very simple yet powerful.
+
+If you have any questions please contact me [@dnagir](http://www.ApproachE.com).
+
+## Why another one?
+
+I've been using really great [cancan](https://github.com/ryanb/cancan) gem by Ryan Bates for a long time.
+It does its job amazingly well.
+
+CanCan doesn't work very well for me when Ability definitions grow above 20 lines or so:
+
+- it becomes **really** hard to track down why something was (or not) allowed.
+- DSL enforces you to use ActiveRecord-like scopes or block to fall back. Those grow and it gets hard to maintain.
+- The Ability class contains all the definitions for everything. Hard to test, hard to maintain.
+- Implicit permission - CanCan tries to be very smart (and is indeed) using aliases such as `:manage` but it makes even harder to maintain.
+- Implicit permission - you can use any symbol to check permissions. `:love_people` will do, even if you never defined it.
+- A little bit tight to ORM. When using with database such as neo4j, some smalish things don't work. So I prefer to be explicit.
+
+So I decided to put up allowy to solve those issue for me.
+
+[Allowy](https://github.com/dnagir/allowy) better suites if you want more control over your authorization. It is inspired by CanCan, but was implemented with simplicity and explicitness in mind.
+
+
+# Install
+
+Add it to your Rails application's `Gemfile`:
+
+```ruby
+gem 'alowy'
+```
+
+Then `bundle install`.
+
+Or use `allowy` gem any other way you are not in Rails.
+
+# Usage
+
+I will be assuming a CMS-like system in the examples below.
+The `Page` class may be ActiveRecord, Mongoid or any other model of your choise. Doesn't matter.
+
+
+## Minimal setup
+
+You define a set of permissions per class.
+If you want to safeguard `Page` class then define `PageAccess` class:
+
+```ruby
+class PageAccess
+  include Allowy::AccessControl
+
+  # This will allow you to ask: can? :view, page
+  # The truthy result of this function will grant access, otherwise not.
+  def view?(page)
+    page and page.published?
+  end
+
+  def edit?(page)
+    page and page.wiki?
+  end
+end
+
+# Then, in rails, you would use it:
+can? :view, page
+cannot? :edit, page
+authorize! :view, page # raises Allowy::AccessDenied if can?(:view, page) return false
+can? :love_people, page # Will fail because `love_people` is not defined on the Access Control class
+```
+
+## Context
+
+You can access current user, request data etc using the `context` method.
+In Rails, the context is set to the current controller, so you have full access to it (not only the current user!).
+
+
+```ruby
+class PageAccess
+  include Allowy::AccessControl
+
+  def view?(page)
+    context.user_signed_in? and page.published?
+  end
+end
+```
+
+If you want to change the context in Rails then just override it on a single controller or globally on the `ApplicationController`:
+
+```ruby
+class DefaultAccess
+  include Allowy::AccessControl
+  # This will give you methods without the need to go to context object
+  delegate :current_user,    :to => :context
+  delegate :current_company, :to => :context
+end
+```
+
+## More comprehensive example
+
+You probably have multiple classes that you want to protect.
+I recommend creating your own base class to provide common context and maybe some utility methods:
+
+```ruby
+class DefaultAccess
+  include Allowy::AccessControl
+end
+```
+
+Then you can create multiple access control classes much easier:
+
+```ruby
+class PageAccess < DefaultAccess
+  # can? :view, page
+  def view?(page)
+    page and page.published?
+  end
+
+  # can? :edit, page
+  def edit?(page)
+    view?(page) and page.wiki? # Notice how we can reuse other definitions!
+  end
+
+  # can? :create, WikiPage
+  def create?(page_class)
+    # We can do something with WikiPage here if we need to
+    # but can just ignore it and authorize based on current context only
+    current_user and current_user.admin?
+  end
+
+  # can? :search, Page, 'Ruby rocks!'
+  def search?(clazz, phrase)
+    # Apart from context, we can require to pass additional parameters
+    create?(Page) and (phrase || '').match /rocks/i
+  end
+end
+```
+
+
+# Testing with RSpec
+
+To test the access control classes you can just instantiate those passing context as a parameter.
+Most of the times you will stub out the context, so more isolated is a piece of cake.
+
+You need to `require 'allowy/rspec'` to enable the RSpec matchers and Rails controller extensions.
+It will give you RSpec matcher `be_able_to` and `ignore_authorization!` macro for controller specs.
+
+
+```ruby
+# spec/models/page_access.rb
+# Example spec for the PageAccess
+describe PageAccess do
+  subject     { PageAccess.new double(current_user: User.new.or_whatever) }
+  let(:page)  { Page.new }
+
+  describe "#view" do
+    it { should_not be_able_to :view, page }
+
+    context "when published" do
+      before { page.publish! }
+      it { should be_able_to :view, page }
+    end
+  end
+
+  # and so on
+end
+
+
+# Example of a controller specs
+describe PagesController do
+  # This will always grant access, so you don't have to create too many objects
+  # But make sure you test PageAccess separately as in the example above
+  ignore_authorization! 
+
+  it "will always allow no matter what" do
+    post(:create).should be_success
+  end
+end
+```
+
+# Development
+
+
+- Source hosted at [GitHub](https://github.com/dnagir/allowy)
+- Report issues and feature requests to [GitHub Issues](https://github.com/dnagir/allowy/issues)
+- Ping me on Twitter [@dnagir](https://twitter.com/#!/dnagir)
+
+
+To start contributing (assuming you already cloned the repo in cd-d into it):
+
+```bash
+bundle install
+# Now run the Ruby specs
+bundle exec rspec spec/
+```
+
+
+Pull requests are very welcome, but please include the specs.
+
+# License
+
+[MIT] (http://www.opensource.org/licenses/mit-license.php)

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/allowy.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "allowy/version"
+
+Gem::Specification.new do |s|
+  s.name        = "allowy"
+  s.version     = Allowy::VERSION
+  s.authors     = ["Dmytrii Nagirniak"]
+  s.email       = ["dnagir@gmail.com"]
+  s.homepage    = ""
+  s.summary     = %q{Authorization with simplicity and explicitness in mind}
+  s.description = %q{Allowy provides CanCan-like way of checking permission but doesn't enforce a tight DSL giving you more control}
+
+  s.rubyforge_project = "allowy"
+
+  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) }
+  s.require_paths = ["lib"]
+
+  s.add_runtime_dependency "activesupport"
+
+  s.add_development_dependency "rspec"
+  s.add_development_dependency "pry"
+  s.add_development_dependency "guard"
+  s.add_development_dependency "guard-rspec"
+end

data/lib/allowy.rb

@@ -0,0 +1,20 @@
+require 'active_support/concern'
+require "allowy/version"
+require "allowy/access_control"
+require "allowy/registry"
+require "allowy/controller_extensions"
+
+module Allowy
+  class UndefinedAccessControl < StandardError; end
+  class UndefinedAction < StandardError; end
+
+  class AccessDenied < StandardError
+    attr_reader :action, :subject
+
+    def initialize(message, action, subject)
+      @message = message
+      @action = action
+      @subject = subject
+    end
+  end
+end

data/lib/allowy/access_control.rb

@@ -0,0 +1,29 @@
+module Allowy
+  module AccessControl
+    extend ActiveSupport::Concern
+    included do
+      attr_reader :context
+    end
+
+    module InstanceMethods
+      def initialize(ctx)
+        @context = ctx
+      end
+
+      def can?(action, *args)
+        m = "#{action}?"
+        raise UndefinedAction.new("The #{self.class.name} needs to have #{m} method. Please define it.") unless self.respond_to? m
+        send(m, *args)
+      end
+
+      def cannot?(*args)
+        not can?(*args)
+      end
+
+      def authorize!(*args)
+        raise AccessDenied.new("Not authorized", args.first, args[1]) unless can?(*args)
+      end
+    end
+
+  end
+end

data/lib/allowy/controller_extensions.rb

@@ -0,0 +1,37 @@
+module Allowy
+
+  module ControllerExtensions
+    extend ActiveSupport::Concern
+    included do
+      helper_method :can?, :cannot?
+    end
+
+    module InstanceMethods
+
+      def allowy_context
+        self
+      end
+
+      def current_allowy
+        @current_allowy ||= ::Allowy::Registry.new(allowy_context)
+      end
+
+      def can?(action, subject, *args)
+        current_allowy.access_control_for!(subject).can?(action, subject, *args)
+      end
+
+      def cannot?(*args)
+        current_allowy.access_control_for!(subject).cannot?(action, subject, *args)
+      end
+
+      def authorize!(action, subject, *args)
+        current_allowy.access_control_for!(subject).authorize!(action, subject, *args)
+      end
+    end
+
+  end
+end
+
+if defined? ActionController
+  ActionController::Base.send(:include, Allowy::ControllerExtensions)
+end

data/lib/allowy/matchers.rb

@@ -0,0 +1,44 @@
+module Allowy
+  module Matchers
+
+    class AbleToMatcher
+      def initialize(action, subject=nil)
+        @action, @subject = action, subject
+      end
+
+      def say msg
+        "#{msg} #{@action} #{@subject.inspect}" + if @context
+          ' with ' + @context.inspect
+        else
+          ''
+        end
+      end
+
+      def matches?(access_control)
+        @context = access_control.context
+        access_control.can?(@action, @subject)
+      end
+
+      def description
+        say "be able to"
+      end
+
+      def failure_message
+        say "expected to be able to"
+      end
+
+      def negative_failure_message
+        say "expected NOT to be able to"
+      end
+    end
+
+    ::RSpec::Matchers.define :be_able_to do |*args|
+      m = AbleToMatcher.new(*args)
+      match                           {|a| m.matches?(a) }
+      failure_message_for_should      { m.failure_message }
+      failure_message_for_should_not  { m.negative_failure_message }
+      description                     { m.description }
+    end
+
+  end
+end

data/lib/allowy/registry.rb

@@ -0,0 +1,33 @@
+module Allowy
+  class Registry
+    def initialize(ctx)
+      @context = ctx
+      @registry = {}
+    end
+
+    def access_control_for!(subject)
+      ac = access_control_for subject
+      raise UndefinedAccessControl.new("Please define Access Control class for #{subject.inspect}") unless ac
+      ac
+    end
+
+    def access_control_for(subject)
+      return unless subject
+      # Try subject as an object
+      clazz = class_for "#{subject.class.name}Access"
+
+      # Try subject as a class
+      clazz = class_for "#{subject.name}Access" if !clazz && subject.is_a?(Class)
+
+      return unless clazz # No luck this time
+      # create a new instance or return existing
+      @registry[clazz] ||= clazz.new(@context)
+    end
+
+    def class_for(name)
+      # TODO: Namespace it
+      return ::Object.const_get(name) if ::Object.const_defined?(name)
+    end
+
+  end
+end

data/lib/allowy/rspec.rb

@@ -0,0 +1,20 @@
+require 'allowy/matchers'
+
+module Allowy
+
+  module ControllerAuthorizationMacros
+    def ignore_authorization!
+      before(:each) do
+        registry = double 'Registry'
+        registry.stub(:can? => true, :cannot? => false, :authorize! => nil, access_control_for!: registry)
+        @controller.stub(:current_allowy).and_return registry
+      end
+    end
+  end
+
+end
+
+RSpec.configure do |config|
+  config.extend Allowy::ControllerAuthorizationMacros, :type => :controller
+end
+

data/lib/allowy/version.rb

@@ -0,0 +1,3 @@
+module Allowy
+  VERSION = "0.1.0"
+end

data/spec/access_control_spec.rb

@@ -0,0 +1,49 @@
+require 'spec_helper'
+
+module Allowy
+  describe "checking permissions" do
+
+    let(:access)  { SampleAccess.new(123) }
+    subject       { access }
+
+    describe "#context as an arbitrary object" do
+      subject     { access.context }
+      its(:to_s)  { should == '123' }
+      its(:zero?) { should be_false }
+      it "should be able to access the context" do
+        access.should be_able_to :context_is_123
+      end
+    end
+
+    it "should allow" do
+      subject.should be_able_to :read, 'allow'
+    end
+
+    it "should deny" do
+      subject.should_not be_able_to :read, 'deny'
+    end
+
+    it "should raise if no permission defined" do
+      lambda { subject.can? :write, 'allow' }.should raise_error(UndefinedAction) {|err|
+        err.message.should include 'write?'
+      }
+    end
+
+
+    describe "#authorize!" do
+      it "shuold raise error" do
+        expect { subject.authorize! :read, 'deny' }.to raise_error AccessDenied do |err|
+          err.message.should_not be_blank
+          err.action.should == :read
+          err.subject.should == 'deny'
+        end
+      end
+
+      it "should not raise error" do
+        expect { subject.authorize! :read, 'allow' }.not_to raise_error AccessDenied
+      end
+    end
+
+  end
+
+end

data/spec/registry_spec.rb

@@ -0,0 +1,36 @@
+require 'spec_helper'
+
+module Allowy
+  describe Registry do
+    let(:context) { 123 }
+    subject       { Registry.new context }
+
+    describe "#access_control_for!" do
+
+      it "should find AC by appending Access to the subject" do
+        subject.access_control_for!(Sample.new).should be_a SampleAccess
+      end
+
+      it "should find AC when the subject is a class" do
+        subject.access_control_for!(Sample).should be_a SampleAccess
+      end
+
+      it "should raise when AC is not found by the subject" do
+        lambda { subject.access_control_for!(123) }.should raise_error(UndefinedAccessControl) {|err|
+          err.message.should include '123'
+        }
+      end
+
+      it "should raise when subject is nil" do
+        lambda { subject.access_control_for!(nil) }.should raise_error UndefinedAccessControl
+      end
+
+      it "should return the same AC instance" do
+        first = subject.access_control_for!(Sample)
+        secnd = subject.access_control_for!(Sample)
+        first.should === secnd
+      end
+
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,24 @@
+require 'pry'
+require 'allowy'
+require 'allowy/matchers'
+
+RSpec.configure do |c|
+  c.treat_symbols_as_metadata_keys_with_true_values = true
+  c.run_all_when_everything_filtered = true
+end
+
+class SampleAccess
+  include Allowy::AccessControl
+
+  def read?(str)
+    str == 'allow'
+  end
+
+  def context_is_123?(*whatever)
+    context === 123
+  end
+end
+
+class Sample
+  attr_accessor :name
+end

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: allowy
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Dmytrii Nagirniak
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-01-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: &70137337531820 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70137337531820
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70137337531300 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70137337531300
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: &70137337530860 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70137337530860
+- !ruby/object:Gem::Dependency
+  name: guard
+  requirement: &70137337530240 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70137337530240
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: &70137337529580 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70137337529580
+description: Allowy provides CanCan-like way of checking permission but doesn't enforce
+  a tight DSL giving you more control
+email:
+- dnagir@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- Guardfile
+- README.md
+- Rakefile
+- allowy.gemspec
+- lib/allowy.rb
+- lib/allowy/access_control.rb
+- lib/allowy/controller_extensions.rb
+- lib/allowy/matchers.rb
+- lib/allowy/registry.rb
+- lib/allowy/rspec.rb
+- lib/allowy/version.rb
+- spec/access_control_spec.rb
+- spec/registry_spec.rb
+- spec/spec_helper.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: allowy
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Authorization with simplicity and explicitness in mind
+test_files:
+- spec/access_control_spec.rb
+- spec/registry_spec.rb
+- spec/spec_helper.rb
+has_rdoc: