aegis 1.1.8 → 2.0.0

data/.gitignore

@@ -0,0 +1,4 @@
+doc
+pkg
+*.gem
+.idea

data/README.rdoc

@@ -1,195 +1,88 @@
-= Aegis - role-based permissions for your user models
+= Aegis - A complete authorization solution for Rails
 
-Aegis allows you to manage fine-grained, complex permission for user accounts in a central place.
+Aegis is an authorization solution for Ruby on Rails that supports roles and a RESTish, resource-style declaration of
+permission rules. Getting started with Aegis is easy and requires very little integration. As your authorization
+requirements become more complex, Aegis will grow with you.
 
-== Installation
-
-Add the following to your <tt>Initializer.run</tt> block in your <tt>environment.rb</tt>:
-    config.gem 'aegis', :source => 'http://gemcutter.org'
-Then do a 
-    sudo rake gems:install
 
-Alternatively, use
-    sudo gem sources -a http://gemcutter.org
-    sudo gem install aegis
+== Getting started
 
-== Example 
-
-First, let's define some roles:
-
-    # app/models/permissions.rb
-    class Permissions < Aegis::Permissions
-
-      role :guest
-      role :registered_user
-      role :moderator
-      role :administrator, :default_permission => :allow
-      
-      permission :edit_post do |user, post|
-        allow :registered_user do
-          post.creator == user      # a registered_user can only edit his own posts
-        end
-        allow :moderator
-      end
-      
-      permission :read_post do |post|
-        allow :everyone
-        deny :guest do
-          post.private?             # guests may not read private posts
-        end
-      end
+All your permissions live in a single class <tt>Permissions</tt>.
+Permissions are described using <tt>resources</tt>, similiar to your routes.
+Your permission resources can match those in your routes, but don't have to.
 
-    end
+Access to resources or individual actions can be granted or denied to specific roles.
 
+  class Permissions < Aegis::Permissions
 
-Now we assign roles to users. For this, the users table needs to have a string
-column +role_name+.
+    role :user
+    role :admin
 
-    # app/models/user.rb
-    class User
-      has_role
+    resources :projects do
+      allow :everyone
     end
 
-
-These permissions may be used in views and controllers:
-    
-    # app/views/posts/index.html.erb
-    @posts.each do |post|
-      <% if current_user.may_read_post? post %>
-        <%= render post %>
-        <% if current_user.may_edit_post? post %>
-          <%= link_to 'Edit', edit_post_path(post) %>
-        <% end %>
-      <% end %>
-    <% end %>
-
-
-    # app/controllers/posts_controller.rb
-    class PostsController
-      # ...
-
-      def update
-        @post = Post.find(params[:id])
-        current_user.may_edit_post! @post    # raises an Aegis::PermissionError for unauthorized access
-        # ...
-      end
-
+    resources :users do
+      allow :admin
     end
 
-== Details
+  end
 
-=== Roles
+To give your user model a role, it needs to have an attribute +role_name+. The <tt>has_role</tt> macro wires everything together:
 
-To equip a (user) model with any permissions, you simply call *has_role* within
-the model:
-    class User < ActiveRecord::Base
-      has_role
-    end
-Aegis assumes that the corresponding database table has a string-valued column
-called +role_name+. You may override the name with the <tt>:name_accessor =>
-:my_role_column</tt> option.
+  class User < ActiveRecord::Base
+    has_role
+  end
 
-You can define a default role for a model by saying
-    class User < ActiveRecord::Base
-      has_role :default => :admin
-    end
-All this will do, is initialize the +role_name+ with the given default when
-<tt>User.new</tt> is called.
-
-The roles and permissions themselves are defined in a class inheriting from
-<b>Aegis::Permissions</b>. To define roles you create a model <tt>permissions.rb</tt>
-and use the *role* method:
-    class Permissions < Aegis::Permissions
-      role 'role_name'
-    end
+You can now check if a user has permission to access a given action in your controllers and views:
+    
+  <% if current_user.may_update_project? @project %>
+    <%= link_to 'Edit', edit_project_path(@project) %>
+  <% end %>
 
-By default, users belonging to this role are not permitted anything. You may
-override this with <tt>:default_permission => :allow</tt>, e.g.
-    role 'admin', :default_permission => :allow
+You can protect all actions in a controller through an Aegis resource with a single line:
 
-=== Permissions
+  class ProjectsController
+    permissions :projects
+  end
 
-Permissions are specified with the *permission* method and *allow* and *deny*
-    permission :do_something do
-        allow :role_a, :role_b
-        deny :role_c
-    end
 
-Your user model just received two methods called <b>User#may_do_something?</b>
-and <b>User#may_do_something!</b>. The first one with the ? returns true for users with
-+role_a+ and +role_b+, and false for users with +role_c+. The second one with the ! raises an
-Aegis::PermissionError for +role_c+.
-
-=== Normalization
-
-Aegis will perform some normalization. For example, the permissions
-+edit_something+ and +update_something+ will be the same, each granting both 
-<tt>may_edit_something?</tt> and <tt>may_update_something?</tt>. The following normalizations
-are active:
-* edit = update
-* show = list = view = read
-* delete = remove = destroy
-
-=== Complex permissions (with parameters)
- 
-*allow* and *deny* can also take a block that may return +true+ or +false+
-indicating if this really applies. So
-    permission :pull_april_fools_prank do
-      allow :everyone do
-        Date.today.month == 4 and Date.today.day == 1
-      end
-    end
-will generate a <tt>may_pull_april_fools_prank?</tt> method that only returns true on
-April 1.
-
-This becomes more useful if you pass parameters to a <tt>may_...?</tt> method, which
-are passed through to the permission block (together with the user object). This
-way you can define more complex permissions like
-    permission :edit_post do |current_user, post|
-      allow :registered_user do
-        post.owner == current_user
-      end
-      allow :admin
-    end
-which will permit admins and post owners to edit posts.
+== Further reading
 
-=== For your convenience
+You are now familiar with the basic use case. Aegis can do a *lot* more than that.
+There is an awesome {documentation wiki}[http://wiki.github.com/makandra/aegis/] with detailled information on many basic and advanced topics, including:
 
-As a convenience, if you create a permission ending in a plural 's', this
-automatically includes the singular form. That is, after
-    permission :read_posts do
-      allow :everyone
-    end
-<tt>.may_read_post? @post</tt> will return true, as well.
+* {Defining roles and basic permissions}[http://wiki.github.com/makandra/aegis/defining-roles-and-basic-permissions]
+* {Checking permissions}[http://wiki.github.com/makandra/aegis/checking-permissions]
+* {Giving your user model a role}[http://wiki.github.com/makandra/aegis/giving-your-user-model-a-role]
+* {Defining permissions with resources}[http://wiki.github.com/makandra/aegis/defining-permissions-with-resources]
+* {Controller integration}[http://wiki.github.com/makandra/aegis/controller-integration]
+* {Giving default access to superusers}[http://wiki.github.com/makandra/aegis/giving-default-access-to-superusers]
+* {Distinguishing between reading and writing actions}[http://wiki.github.com/makandra/aegis/distinguishing-between-reading-and-writing-actions]
+* {Aliasing actions}[http://wiki.github.com/makandra/aegis/aliasing-actions]
+* {Checking permissions when no user is signed in}[http://wiki.github.com/makandra/aegis/checking-permissions-when-no-user-is-signed-in]
+* {Handling denied permissions in your controllers}[http://wiki.github.com/makandra/aegis/handling-denied-permissions-in-your-controllers]
+* {Changing behavior when a permission is undefined}[http://wiki.github.com/makandra/aegis/changing-behavior-when-a-permission-is-undefined]
+* {Multiple roles per user}[http://wiki.github.com/makandra/aegis/multiple-roles-per-user]
+* {Upgrading to Aegis 2}[http://wiki.github.com/makandra/aegis/upgrading-to-aegis-2]
 
-If you want to grant +create_something+, +read_something+, +update_something+
-and +destroy_something+ permissions all at once, just use
-    permission :crud_something do
-      allow :admin
-    end
-
-If several permission blocks (or several allow and denies) apply to a certain
-role, the later one always wins. That is
-    permission :do_something do
-      deny :everyone
-      allow :admin
-    end
-will work as expected.
 
-=== Our stance on multiple roles per user
+== Installation
 
-We believe that you should only distinguish roles that have different ways of resolving their permissions. A typical set of roles would be
+Add the following to your <tt>Initializer.run</tt> block in your <tt>environment.rb</tt>:
+    config.gem 'aegis', :source => 'http://gemcutter.org'
+Then do a
+    sudo rake gems:install
 
-* anonymous guest (has access to nothing with some exceptions)
-* signed up user (has access to some things depending on its attributes and associations)
-* administrator (has access to everything)
+Alternatively, use
+    sudo gem sources -a http://gemcutter.org
+    sudo gem install aegis
 
-We don't do multiple, parametrized roles like "leader for project #2" and "author of post #7". 
-That would be reinventing associations. Just use a single :user role and let your permission block
-query regular associations and attributes.
 
-=== Credits
+== Credits
 
 Henning Koch, Tobias Kraze
 
-{link www.makandra.de}[http://www.makandra.de/]
+{gem-session.com}[http://gem-session.com/]
+
+{www.makandra.de}[http://www.makandra.de/]

data/Rakefile

@@ -1,26 +1,34 @@
 require 'rake'
-require 'rake/testtask'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
 
-desc 'Default: run unit tests.'
-task :default => :test
+desc 'Default: Run Aegis specs'
+task :default => :spec
 
-desc 'Test the aegis gem.'
-Rake::TestTask.new(:test) do |t|
-  t.libs << 'lib'
-  t.pattern = 'test/**/*_test.rb'
-  t.verbose = true
+desc "Run Aegis specs"
+Spec::Rake::SpecTask.new() do |t|
+  t.spec_opts = ['--options', "\"spec/spec.opts\""]
+  t.spec_files = FileList['spec/**/*_spec.rb']
 end
 
+desc 'Generate documentation for the Aegis gem'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Aegis'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
 
 begin
   require 'jeweler'
   Jeweler::Tasks.new do |gemspec|
     gemspec.name = "aegis"
-    gemspec.summary = "Role-based permissions for your user models."
-    gemspec.email = "github@makandra.de"
+    gemspec.summary = "Complete authorization solution for Rails"
+    gemspec.email = "henning.koch@makandra.de"
     gemspec.homepage = "http://github.com/makandra/aegis"
-    gemspec.description = "Aegis is a role-based permission system, where all users are given a role. It is possible to define detailed and complex permissions for each role very easily."
-    gemspec.authors = ["Henning Koch"]
+    gemspec.description = "Aegis is an authorization solution for Ruby on Rails that supports roles and a RESTish, resource-style declaration of permission rules."
+    gemspec.authors = ["Henning Koch", "Tobias Kraze"]
   end
 rescue LoadError
   puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"

data/VERSION

@@ -1 +1 @@
-1.1.8
+2.0.0

data/aegis.gemspec

@@ -1,77 +1,106 @@
 # Generated by jeweler
-# DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
-  s.name = "aegis"
-  s.version = "1.1.8"
+  s.name = %q{aegis}
+  s.version = "2.0.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Henning Koch"]
-  s.date = "2014-05-28"
-  s.description = "Aegis is a role-based permission system, where all users are given a role. It is possible to define detailed and complex permissions for each role very easily."
-  s.email = "github@makandra.de"
+  s.authors = ["Henning Koch", "Tobias Kraze"]
+  s.date = %q{2010-05-02}
+  s.description = %q{Aegis is an authorization solution for Ruby on Rails that supports roles and a RESTish, resource-style declaration of permission rules.}
+  s.email = %q{henning.koch@makandra.de}
   s.extra_rdoc_files = [
     "README.rdoc"
   ]
   s.files = [
-    "MIT-LICENSE",
-    "README.rdoc",
-    "Rakefile",
-    "VERSION",
-    "aegis.gemspec",
-    "lib/aegis.rb",
-    "lib/aegis/constants.rb",
-    "lib/aegis/has_role.rb",
-    "lib/aegis/normalization.rb",
-    "lib/aegis/permission_error.rb",
-    "lib/aegis/permission_evaluator.rb",
-    "lib/aegis/permissions.rb",
-    "lib/aegis/role.rb",
-    "lib/rails/active_record.rb",
-    "test/app_root/app/controllers/application_controller.rb",
-    "test/app_root/app/models/old_soldier.rb",
-    "test/app_root/app/models/permissions.rb",
-    "test/app_root/app/models/soldier.rb",
-    "test/app_root/app/models/trust_fund_kid.rb",
-    "test/app_root/app/models/user.rb",
-    "test/app_root/app/models/user_subclass.rb",
-    "test/app_root/app/models/veteran_soldier.rb",
-    "test/app_root/config/boot.rb",
-    "test/app_root/config/database.yml",
-    "test/app_root/config/environment.rb",
-    "test/app_root/config/environments/in_memory.rb",
-    "test/app_root/config/environments/mysql.rb",
-    "test/app_root/config/environments/postgresql.rb",
-    "test/app_root/config/environments/sqlite.rb",
-    "test/app_root/config/environments/sqlite3.rb",
-    "test/app_root/config/routes.rb",
-    "test/app_root/db/migrate/20090408115228_create_users.rb",
-    "test/app_root/db/migrate/20090429075648_create_soldiers.rb",
-    "test/app_root/db/migrate/20091110075648_create_veteran_soldiers.rb",
-    "test/app_root/db/migrate/20091110075649_create_trust_fund_kids.rb",
-    "test/app_root/lib/console_with_fixtures.rb",
-    "test/app_root/log/.gitignore",
-    "test/app_root/script/console",
-    "test/has_role_options_test.rb",
-    "test/has_role_test.rb",
-    "test/permissions_test.rb",
-    "test/test_helper.rb",
-    "test/validation_test.rb"
+    ".gitignore",
+     "MIT-LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "aegis.gemspec",
+     "lib/aegis.rb",
+     "lib/aegis/access_denied.rb",
+     "lib/aegis/action.rb",
+     "lib/aegis/compiler.rb",
+     "lib/aegis/has_role.rb",
+     "lib/aegis/parser.rb",
+     "lib/aegis/permissions.rb",
+     "lib/aegis/resource.rb",
+     "lib/aegis/role.rb",
+     "lib/aegis/sieve.rb",
+     "lib/rails/action_controller.rb",
+     "lib/rails/active_record.rb",
+     "spec/action_controller_spec.rb",
+     "spec/app_root/app/controllers/application_controller.rb",
+     "spec/app_root/app/controllers/reviews_controller.rb",
+     "spec/app_root/app/models/permissions.rb",
+     "spec/app_root/app/models/property.rb",
+     "spec/app_root/app/models/review.rb",
+     "spec/app_root/app/models/user.rb",
+     "spec/app_root/config/boot.rb",
+     "spec/app_root/config/database.yml",
+     "spec/app_root/config/environment.rb",
+     "spec/app_root/config/environments/in_memory.rb",
+     "spec/app_root/config/environments/mysql.rb",
+     "spec/app_root/config/environments/postgresql.rb",
+     "spec/app_root/config/environments/sqlite.rb",
+     "spec/app_root/config/environments/sqlite3.rb",
+     "spec/app_root/config/routes.rb",
+     "spec/app_root/db/migrate/001_create_users.rb",
+     "spec/app_root/db/migrate/002_create_properties.rb",
+     "spec/app_root/db/migrate/003_create_reviews.rb",
+     "spec/app_root/lib/console_with_fixtures.rb",
+     "spec/app_root/log/.gitignore",
+     "spec/app_root/script/console",
+     "spec/controllers/reviews_controller_spec.rb",
+     "spec/has_role_spec.rb",
+     "spec/permissions_spec.rb",
+     "spec/rcov.opts",
+     "spec/spec.opts",
+     "spec/spec_helper.rb"
   ]
-  s.homepage = "http://github.com/makandra/aegis"
+  s.homepage = %q{http://github.com/makandra/aegis}
+  s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
-  s.rubygems_version = "1.8.25"
-  s.summary = "Role-based permissions for your user models."
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Complete authorization solution for Rails}
+  s.test_files = [
+    "spec/app_root/app/models/user.rb",
+     "spec/app_root/app/models/property.rb",
+     "spec/app_root/app/models/review.rb",
+     "spec/app_root/app/models/permissions.rb",
+     "spec/app_root/app/controllers/application_controller.rb",
+     "spec/app_root/app/controllers/reviews_controller.rb",
+     "spec/app_root/config/boot.rb",
+     "spec/app_root/config/environment.rb",
+     "spec/app_root/config/environments/in_memory.rb",
+     "spec/app_root/config/environments/mysql.rb",
+     "spec/app_root/config/environments/postgresql.rb",
+     "spec/app_root/config/environments/sqlite.rb",
+     "spec/app_root/config/environments/sqlite3.rb",
+     "spec/app_root/config/routes.rb",
+     "spec/app_root/db/migrate/001_create_users.rb",
+     "spec/app_root/db/migrate/002_create_properties.rb",
+     "spec/app_root/db/migrate/003_create_reviews.rb",
+     "spec/app_root/lib/console_with_fixtures.rb",
+     "spec/action_controller_spec.rb",
+     "spec/has_role_spec.rb",
+     "spec/permissions_spec.rb",
+     "spec/spec_helper.rb",
+     "spec/controllers/reviews_controller_spec.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
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
     else
     end
   else
   end
 end
-