aclatraz 0.0.1 → 0.1.0

data/CHANGELOG.rdoc

@@ -0,0 +1,21 @@
+== Version 0.1.0
+
+* Inherited access control lists
+* Optimized Aclatraz::Guard & Aclatraz::ACL
+* Added aliases: #access_control for #suspects and #authorize! for #guard! in Aclatraz::Guard
+* Added #init to Aclatraz
+* Added Aclatraz::Suspect::Roles
+* Added #roles proxy instead of #assign_role!, #delete_role!, #has_role? in Aclatraz::Suspect
+* Defining permissions in #guard! block
+
+* README documentation
+* Code documentation
+
+== Version 0.0.1 (proof of concept)
+
+* Redis store
+* Flat access control lists
+* Semantic permissions in suspect
+
+* Basic documentation
+* Benchmarks

data/README.rdoc

@@ -5,92 +5,256 @@ powered by fast key value stores like Redis or TokyoCabinet.
 
 == Installation
 
-You can install ACLatraz via rubygems:
+You can simple install ACLatraz via rubygems:
 
-  sudo gem install ACLatraz
+  sudo gem install aclatraz
   
-== Basic usage
+== Configuration
 
-First of all you have to setup store for ACL data. ACLatraz for now uses only 
-Redis database for storage. Store can be set like below:
+Before you'll start play with access controll in your apps you have to 
+correctly configure datastore for permissions (at this moment ACLatraz
+is only supporting Redis database as storage). Redis datastore configuration
+looks very simple:
 
-  Aclatraz.store :redis, "redis://localhost:6379/0"
+  Aclatraz.init :redis, "redis://localhost:6379/0"
   
-Then you have to define your suspects:  
+Remember that using Redis, you should specify database dedicated only for ACLatraz.   
+
+== Suspects
+
+Suspects are objects which we can assign specific permissions. There is only 
+one condition which object have to meet to be suspect - it must have the #id
+method which returns an unique identifier after which we will be able to
+reference this object. To enable suspect behaviour you have to include the
++Aclatraz::Suspect+ module to specified class, eg:
 
   class Account < ActiveRecord::Base
     include Aclatraz::Suspect
   end
   
-Now you suspect have few methods which will helps you with managing permissions:
-
-  @account = Account.create
-  @account.has_role?(:foo)     # => false
-  @account.is.foo?             # syntactic sugar for #has_role?
-  @account.assign_role!(foo)   # or @account.is.foo!
-  @account.is.foo?             # => true
-  @account.delete_role!(foo)   # or @account.is_not.foo!
-  @account.is.foo?             # => false
-  @account.is_not.foo?         # => true
+Now your suspect have few methods which will helps you manage it permissions.
+
+=== Managing roles
+
+ACLatraz distinguishes between three types of roles:
+
+*global* :: 
+  simple roles, which are most commonly assigned to many users. We can say that 
+  they are kind of groups. Global roles are eg. _guest_, _admin_, _customer_.
+*class-related* :: 
+  roles that affects management of a particular class. Example of this kind
+  of role can be *manager* of +Pages+, *admin* of +Products+, etc.  
+*object-related* ::
+  roles that affects management of an object. For example *author* of 
+  _specified page_, *owner* of _specified product_, etc. 
+
+Now there is two ways for managing roles. You can use +#roles+ or semanticaly 
+look like +#is+ and +#is_not+ proxies. 
+
+==== Assigning
+
+To add given role you can use +#assign+ method from +#roles+ proxy or use
+semantic shortcuts. Semantic shortcut have to ends with *!*, and can have
+optional suffixes: <em>_on</em>, <em>_of</em>, <em>_at</em>, <em>_for</em>,
+<em>_in</em>, <em>_by</em>. Take a look at the following examples to get 
+everything to be clear: 
+
+  @account.roles.assign(:admin) # or ...
+  @account.is.admin!
+  
+...will assign *global* _admin_ role to the account.
+ 
+  @account.roles.assign(:responsible, Foo) # or...
+  @account.is.responsible_for!(Foo)
+ 
+...will assign to the account _responsible_ role related with Foo class. 
+
+  @account.roles.assign(:author, Page.find(15)) # or...
+  @account.is.author_of!(Page.find(15))
+  
+...will assign to the account _author_ role related with given page object. 
+
+==== Checking
+
+Using #roles proxy you can call +#has?+ method on it, eg: 
+
+  @account.roles.has?(:admin)                # => true
+  @account.roles.has?(:responsible, Foo)     # => true
+  @account.roles.has?(:author, Page.find(15) # => true
+
+With semantic shortcuts your method name have to ends with *?* and can contain 
+any of suffixes listed above, eg:
+
+  @account.is.admin?                   # => true
+  @account.is.responsible_for?(Foo)    # => true
+  @account.is.author_of(Page.find(15)) # => true
+
+Few more examples with semantic negation:
+
+  @account.is_not.admin?               # => false
+  @account.is_not.responsible_for(Foo) # => false
+
+==== Deleting
+
+To unassign given role from object use +#delete+ method from +#roles+, eg:
+
+  @account.roles.delete(:admin)
+  @account.roles.delete(:responsible, Foo)
+  
+Another way is to use semantic negation, where method name have to ends with *!* 
+and can contain one of allowed suffixes, eg:
+
+  @account.is_not.admin!
+  @account.is_not.author_of(Page.find(15))
   
-Last step is create you access control list and set guards:
+== Guards
+
+To enable access control in your for your objects you have to include to it the 
++Aclatraz::Guard+ module. This module provides methods for defining and checking
+permissions of an suspected object. Take a look for this basic example:
 
   class Foo
     include Aclatraz::Guard
+
+    suspects :account do 
+      deny all # notice that it's a method, not symbol
+      allow :admin
+    end
+  end 
+ 
+The +#suspects+ block is passing one argument - suspected object. When there is
+symbol given, like in example above, then will treat #account instance method
+result as suspected object. When you will use string, eg:
+
+  suspects "account" do # or suspects "@account" do ...
+  
+... it will treat @account instance variable as suspect. You can also specify 
+suspected object directly, eg:
+
+  account = Account.find(1)
+  suspects account do # ...
+  
+=== Allowing and denying access
+
+As you probably noticed, there is two methods responsible for access control, 
+namely +#allow+ and +#deny+. As its argument you can pass simple name of role
+or permission statement, eg:
+
+  allow :admin
+  deny :guest
+  allow :responsible_for => Foo
+  allow :author_of => "@page"  
+ 
+Like you see, you can easy specify access for each kind of role. The object-related
+permissions behaviour is similar to +#suspects+ method. When given related object
+is string then applies permissions for an instance variable, when symbol then 
+applies it for instance method, otherwise directly for given object.
+
+=== Actions
+
+In your access control block you can specify separate action with its own 
+permissions, eg:
+
+  suspects :account do 
+    deny all
+    allow :admin
+    
+    action :manage do 
+      allow :responsible_for => Foo
+    end
     
-    suspect :account do 
-      allow all
-      
-      on :manage do 
-        allow :root
-        allow :manager
+    action :delete do 
+      allow :author_of => "@page"
+    end
+  end
+  
+Obviously all actions inherits all permissions from main block.  
+ 
+=== Authorizing
+
+The +Aclatraz::Guards+ module provides +#guard!+ method for checking permissions.
+When suspected object don't have any of allowed permissions or have any of defnied
+then it will raise the +Aclatraz::AccessDenied+ error. Here's an comprehensive example:
+
+  class Foo
+    suspects "@account" do 
+      deny all
+      allow :admin
+      action :foo
+        allow :foo
       end
-      
-      on :delete do 
-        deny :manager
-        allow :owner_of => "@project" 
+      action :bar
+        allow :bar
+        deny :admin
       end
     end
-    
-    # The #suspect method allows to pass String, Symbol or Object as suspect. 
-    # When String given (eg. "account" or "@account") then value of given 
-    # instance variable will be treated as suspect. When Symbol given, then 
-    # system will take value from given instance method. Otherwise given object
-    # will be treated as suspect if possible. 
-    #
-    # Similar situation is with permission arguments. To #allow and #deny 
-    # methods you can pass symbol or hash. Symbol given represents
-    # single role, the hash represents ownership of assigned object or class.
-    # Assigned object declaration behaves the same as suspects' one. 
-    
-    def account
-      @account ||= Account.find(ENV['MYAPP_ACCOUNT'])
+
+    def initialize(account)
+      @account = account
     end
     
-    def index
+    def simple
       guard!
-      # ... everybody are allowed to see this
+      # only for accounts with :admin role...
     end
     
-    def create
-      guard!(:manage)
-      # ... only managers and root will see this
+    def foo
+      guard!(:foo)
+      # only for accounts with :admin or :foo role...
     end
     
-    def delete(id)
-      @product = Product.find(id)
-      guard!(:manage, :delete)
-      # ... only root or or @product owner will see this
+    def bar
+      guard!(:bar)
+      # only for accounts with :bar role...
     end
     
-    def product(id)
-      @product.find(id)
-      account.is.owner_of?(@product) do
-        return @product
-      end
-      return nil
+    def foobar
+      guard!(:foo, :bar)
+      # only for accounts with :foo or :bar, and mandatory without :admin role...
     end
   end
+ 
+There is also a very nice feature. You can define additional permissions directly
+in +#guard!+ block, eg:
+
+  def foo
+    guard! do
+      allow :foo
+      deny :bar
+    end
+    # ...
+  end
+ 
+=== Inheritance
+
+ACLatraz access control supports inheritance. It means that when you define 
+your ACL in parent class it will be applied also for all child classes. Obviously 
+in each child class you can freely modify permissions. Here's an example:  
+
+  class Foo 
+    suspects :account do
+      deny all
+      allow :admin
+    end
+  end
+
+  class Bar < Foo
+    suspects do 
+      # notice, that in child class don't have to again specify suspect...
+      allow :foobar
+    end
+  end  
+  
+  class Spam < Foo
+    suspects :egg do 
+      # but of course you can specify different suspect than in parent class...    
+    end  
+  end
+  
+=== Aliases
+
+If you prefer you can use aliases: +#access_control+ instead of +#suspects+ and 
++#authorize!+ instead of +#guard!+.   
 
 == Note on Patches/Pull Requests
  

data/Rakefile

@@ -6,14 +6,16 @@ begin
   Jeweler::Tasks.new do |gem|
     gem.name = "aclatraz"
     gem.summary = %Q{Flexible access control that doesn't sucks!}
-    gem.description = %Q{Extremaly fast and flexible access control mechanism inspired by *nix ACLs, powered by fast key value stores like Redis or TokyoCabinet.}
+    gem.description = <<-DESCR
+      Extremaly fast and flexible access control mechanism inspired by *nix ACLs, 
+      powered by fast key value stores like Redis or TokyoCabinet.
+    DESCR
     gem.email = "kriss.kowalik@gmail.com"
     gem.homepage = "http://github.com/nu7hatch/aclatraz"
     gem.authors = ["Kriss 'nu7hatch' Kowalik"]
     gem.add_development_dependency "rspec", ">= 1.2.9"
     gem.add_development_dependency "mocha", ">= 0.9"
     gem.add_development_dependency "redis", "~> 2.0"
-    #gem.add_development_dependency "tokyocabinet", ">= XX"
     gem.add_dependency "dictionary", "~> 1.0"
   end
   Jeweler::GemcutterTasks.new
@@ -44,3 +46,8 @@ Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
+
+task :benchmark do 
+  require 'benchmark'
+  require File.dirname(__FILE__)+"/spec/alcatraz_bm"
+end

data/TODO.rdoc

@@ -0,0 +1,6 @@
+== TODO
+
+* TokyoCabinet store
+* Memcached store
+* Think that the main roles should have an impact on object/class ownerships
+* More Examples

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.1.0

data/aclatraz.gemspec

@@ -0,0 +1,88 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{aclatraz}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Kriss 'nu7hatch' Kowalik"]
+  s.date = %q{2010-09-16}
+  s.description = %q{      Extremaly fast and flexible access control mechanism inspired by *nix ACLs, 
+      powered by fast key value stores like Redis or TokyoCabinet.
+}
+  s.email = %q{kriss.kowalik@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "CHANGELOG.rdoc",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "TODO.rdoc",
+     "VERSION",
+     "aclatraz.gemspec",
+     "examples/dinner.rb",
+     "lib/aclatraz.rb",
+     "lib/aclatraz/acl.rb",
+     "lib/aclatraz/guard.rb",
+     "lib/aclatraz/helpers.rb",
+     "lib/aclatraz/store.rb",
+     "lib/aclatraz/store/redis.rb",
+     "lib/aclatraz/suspect.rb",
+     "spec/aclatraz/acl_spec.rb",
+     "spec/aclatraz/guard_spec.rb",
+     "spec/aclatraz/helpers_spec.rb",
+     "spec/aclatraz/stores_spec.rb",
+     "spec/aclatraz/suspect_spec.rb",
+     "spec/aclatraz_spec.rb",
+     "spec/alcatraz_bm.rb",
+     "spec/spec.opts",
+     "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/nu7hatch/aclatraz}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Flexible access control that doesn't sucks!}
+  s.test_files = [
+    "spec/alcatraz_bm.rb",
+     "spec/spec_helper.rb",
+     "spec/aclatraz/guard_spec.rb",
+     "spec/aclatraz/helpers_spec.rb",
+     "spec/aclatraz/acl_spec.rb",
+     "spec/aclatraz/stores_spec.rb",
+     "spec/aclatraz/suspect_spec.rb",
+     "spec/aclatraz_spec.rb",
+     "examples/dinner.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
+      s.add_development_dependency(%q<mocha>, [">= 0.9"])
+      s.add_development_dependency(%q<redis>, ["~> 2.0"])
+      s.add_runtime_dependency(%q<dictionary>, ["~> 1.0"])
+    else
+      s.add_dependency(%q<rspec>, [">= 1.2.9"])
+      s.add_dependency(%q<mocha>, [">= 0.9"])
+      s.add_dependency(%q<redis>, ["~> 2.0"])
+      s.add_dependency(%q<dictionary>, ["~> 1.0"])
+    end
+  else
+    s.add_dependency(%q<rspec>, [">= 1.2.9"])
+    s.add_dependency(%q<mocha>, [">= 0.9"])
+    s.add_dependency(%q<redis>, ["~> 2.0"])
+    s.add_dependency(%q<dictionary>, ["~> 1.0"])
+  end
+end
+