annotation_security 1.0.1 → 1.0.2

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+Changelog
+=========
+
+1.0.2
+-----
+
+* dropped rails 2.3.8 support in favour of rails 2.3.18 support
+* updated docs
+
+
+1.0.1
+-----
+
+* first public release

data/HOW-TO.md

@@ -0,0 +1,275 @@
+# How to secure your Rails application with Annotation Security
+
+## Step 0: Install Annotation Security
+
+Annotation Security comes as a gem hosted on rubygems.org. You can install it
+via `gem install annotation_security`.
+The gem contains a binary called `annotation_security`. It can be used to
+install the security layer into a rails app via
+`annotation_security --rails RAILS_HOME`. This will make your app ready to be
+secured.
+
+### Version Notes
+
+Use the gem version < 2 for Rails 2.3.x applications.
+Use the gem version 3.x for Rails 3.x applications.
+
+## Step 1: Defining user and roles
+
+Annotation Security assumes that there is a user class, representing the user,
+and some role classes containing additional information if the user has a
+certain role in the application.
+
+If you don't have user or role classes in your application,
+continue with step 2.
+
+### User
+
+In most cases the user class will be a subclass of `ActiveRecord::Base`,
+but this is not necessary.
+
+Include the `module AnnotationSecurity::User` into this class.
+
+    class User < ActiveRecord::Base
+      include AnnotationSecurity::User
+      ...
+
+### Roles
+
+Include the module `AnnotationSecurity::Role` into these classes. If you are
+having a hierachy of role classes, only include the module in the topmost class.
+
+    class Role < ActiveRecord::Base
+      belongs_to :user
+      include AnnotationSecurity::Role
+      ...
+
+    class Student < Role
+      # no include here
+      ...
+
+A role object should respond to `user` with returning the user object
+it belongs to.
+
+__Do not include both modules in one class!__
+
+### Connecting user and roles
+
+As next, you should provide some default methods for accessing the roles
+of a user. You can skip this step, but it will be helpfull later on.
+
+There are two types of access methods: `is_ROLE?` and `as_ROLE`.
+
+IS-methods return true or false whether a user has a role or not.
+ 
+    class User < ActiveRecord::Base
+      def is_administrator?
+        self.admin_flag == 1
+      end
+
+      def is_student?
+        self.roles.any? { |role| role.is_a? Student }
+      end
+      ...
+
+AS-methods return a single object or an array of objects representing the role.
+If the user does not have the role, the result should be an empty array or nil.
+    
+    class User < ActiveRecord::Base
+      def as_administrator
+        # there is no administrator class, just return the user
+        is_administrator? ? self : nil
+      end
+      
+      def as_student
+        # assuming a user can only be student once
+        self.roles.detect { |role| role.is_a? Student }
+      end
+      
+      def as_corrector
+        # assuming a user can be a corrector several times
+        self.roles.select { |role| role.is_a? Corrector }
+      end
+
+## Step 2: Providing the current credential
+
+To evaluate the security policies, for each request the current credential has
+to be provided. Therefore, a new filter type was introduced: security filters
+are around filters that are always the first in the filter chain. You can also
+use these filters to react to security violations.
+
+In this example, the user is simply fetched from the session. However, you
+could also pass a symbol or a string (e.g. if you are using API-keys).
+
+Passing `nil` will be interpreted as not being authenticated in any way.
+
+    class ApplicationController < ActionController::Base
+    
+      security_filter :security_filter
+
+      private
+
+      def security_filter
+        SecurityContext.current_credential = session[:user]
+        yield
+      rescue SecurityViolationError
+        if SecurityContext.is? :logged_in
+         render :template => "welcome/not_allowed"
+        else
+         render :template => "welcome/please_login"
+        end
+      end
+
+Please notice that once set, the credential cannot be changed.
+
+## Step 3: Defining your resources
+
+Another wild assumption we made is that your application contains some resources
+you want to protect. In most cases, this will be your ActiveRecord classes.
+To turn them into resources, just call `resource(symbol)` in the class
+definition.
+
+    class Course < ActiveRecord::Base
+      resource :course
+      ...
+
+The symbol is used to further identify this class and should be unique.
+
+It is possible (and likely) that the users and roles are resources as well.
+
+If you want to restrict access to other resource classes, see
+`AnnotationSecurity::Resource` for more information.
+
+## Step 4: Defining relations and rights
+
+in `config/security` you will find the files `relations.rb` and
+`rights.yml`.
+
+### Relations
+
+The relations between the user (or the roles) and the resources are defined
+as code blocks, that evaluate to true or false.
+
+The `:as`-flag causes that instead of the user object, a role object
+will be passed into the block (using the `as_ROLE`-method from above).
+Similar, the `:is`-flag can be used as precondition.
+
+    AnnotationSecurity.define_relations do
+      resource :course do
+        enrolled :as => :student { |student,course| course.students.include? student }
+        corrector :as => :corrector { |corrector,course| corrector.corrects? course }
+        lecturer :as => :lecturer { |lecturer,course| lecturer.lectures? course }
+      end
+      ...
+
+You can also define relations that are valid for all resources.
+
+    all_resources do
+      # corrector and lecturer are defined by the resource
+      responsible { corrector or lecturer }
+      # no block required here
+      administrator :is => :administrator
+    end
+
+For more details and features on defining relations,
+see `AnnotationSecurity::RelationLoader`.
+
+### Rights
+
+The rights of application are specified in a YAML-file, they correspond to the
+actions(not necessarily the controller actions) that can be performed on a
+resource. For instance, to edit a course object, you will need the edit-right
+for the course resource. If you are not sure which rights your application
+needs, just skip this now and return after step 5.
+
+Rights should be valid ruby conditional statements.
+
+    course:
+      create: if lecturer
+      show: if enrolled or responsible
+      edit: if responsible
+
+AnnotationSecurity provides two default relations: `logged_in`, that is true
+if there is a user at all, and +self+, that can be used to determine if a user
+or role resource belongs to the current user.
+
+    user:
+      register: unless logged_in
+      show: if logged_in
+      edit: if self or administrator
+    student:
+      show_results: if self
+
+To improve readability, you can append 'may', 'is', 'can' or 'has' as prefix and
+'for', 'in', 'of' or 'to' as suffix to the relation name.
+This is especially recommended if you are defining rights that depend on
+other rights of the resource.
+
+    assignment:
+      edit: if responsible
+      delete: if may_edit
+
+Another example can be found at `AnnotationSecurity::RightLoader`.
+
+## Step 5: Securing your actions
+
+The main goal of AnnotationSecurity was to remove security logic from
+controller actions. Now you only have to define the abstract effects of an
+action.
+
+An action performs one or more tasks on different resources. You have to provide
+this information as a descriptions, using the
+[Action Annotation Gem](http://github.com/Nikku/action_annotation).
+A description always has the form 'ACTION on RESOURCE'.
+
+    desc 'shows a course'
+    def show
+      @course = Course.find(params[:id])
+    end
+
+To perform a task, the user must have the right for it. Thus, when a course is
+fetched from the database during the show-action, the right course/show will be
+evaluated for the current user and the course instance.
+
+In our example, the user has to be responsible or enrolled. If both relations
+evaluate to false, the right is not given and access will be denied by raising
+a SecurityViolationError, which will then be catched in the security filter.
+
+Congratulations, you Rails application is secured now.
+
+## Step 6: Securing your views
+
+However, actions aren't the only place with security code. Links to the actions
+are shown in the view and very often, the view itself depends on the
+user's rights.
+
+When setting up Annotation Security in your Rails project, a helper will be
+included automatically. The most important functions this helper provides are
+`allowed?` and `link_to_if_allowed`.
+
+The method `allowed?` expects a right and a resource and returns true iif
+the current user has that right.
+
+    <% unless allowed? :edit, @course %>
+      <p>You may not edit this course!</p>
+    <% end %>
+
+`link_to_if_allowed` expects the same arguments as +link_to+, except it also
+expects a block like +link_to_if+ (which will be called internally).
+
+    <%= link_to_if_allowed("New", new_course_path) { "You may not create a new course." } %>
+    <%= link_to_if_allowed("Edit", edit_course_path(@course)) { } %>
+    <%= link_to_if_allowed("Delete", @course, {:method => :delete}) { } %>
+
+`link_to_if_allowed` tries to automatically detect the accessed resources.
+In case this should not work for you, see `AnnotationSecurity::Helper` for more
+features.
+
+## Step 7: Live long and prosper
+
+Well, that's it. Here are some additional notes:
+
+* in development mode, the rights and relations are reloaded with every request.
+* See `AnnotationSecurity::RelationLoader` and `AnnotationSecurity::RightLoader`
+  for more examples and features for defining relations and rights.
+* See `AnnotationSecurity::Helper` for more methods for securing your views.

data/{MIT-LICENSE → LICENSE}

@@ -1,4 +1,4 @@
-Copyright (c) 2009 Nico Rehwaldt, Arian Treffer
+Copyright (c) 2009, 2010, 2013 Nico Rehwaldt, Arian Treffer
 
 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

data/README.md

@@ -0,0 +1,39 @@
+# Resource Based security for Rails applications
+
+This plugin provides a thin security layer for rails applications. It performs access
+checks based on a behavioural description of controller actions. Security rules
+are defined on a resource model which is cleanly separated from your models and controllers.
+
+## Installation steps
+
+The security layer is a gem and may be installed using
+`gem install annotation_security`.
+
+After installing the gem, run `annotation_security --rails RAILS_HOME` to
+integrate the security layer in your rails app. Along with the
+annotation_security plugin this will add
+
+* the `AnnotationSecurity::Helper` in the `app/helpers` folder of your
+  rails-app. It provides some useful methods to create links and query the
+  security layer from views.
+* example configuration files to setup the security layer under `config/security`
+* an initializer for the security layer under `config/initializer`
+
+## Where to start
+
+Check out the basic introduction on [how to secure your application](HOW-TO.md).
+In order to get a detailed idea about how things work, have a deeper look
+inside `AnnotationSecurity::ActionController` (how to secure your application),
+`AnnotationSecurity::RightLoader` (how to setup rights) and
+`AnnotationSecurity::RelationLoader` (how to setup relations).
+
+Have a look at the view methods provided by the `AnnotationSecurity::Helper` as
+well and at the `SecurityContext` which is the main entry-point for security related
+functionality in the layer.
+
+## License
+
+Copyright Nico Rehwaldt, Arian Treffer 2009, 2010, 2013
+
+You may use, copy and redistribute this library under the same terms as
+[Ruby itself](http://www.ruby-lang.org/en/LICENSE.txt) or under the MIT license.

data/Rakefile

@@ -1,56 +1,63 @@
-# 
-# To change this template, choose Tools | Templates
-# and open the template in the editor.
- 
-
-require 'rubygems'
-require 'rake'
-require 'rake/clean'
-require 'rake/gempackagetask'
-require 'rake/rdoctask'
-require 'spec/rake/spectask'
-
-spec = Gem::Specification.new do |s|
-  s.name = 'annotation_security'
-  s.version = '1.0.1'
-  s.has_rdoc = true
-  s.extra_rdoc_files = ['README', 'MIT-LICENSE', 'CHANGELOG', 'HOW-TO']
-  s.summary = 'A role based security model for rails applications with ' +
-              'descriptive definitions and automated evaluation.'
-  s.description =
-    'AnnotationSecurity provides a role based security model with automated ' +
-    'rule evaluation for Ruby on Rails. It allows you to define user-resource-'+
-    'relations and rights in separate files, keeping your controllers and ' +
-    'views free from any security logic. See the gem\'s homepage for an ' +
-    'example.'
-  s.author = 'Nico Rehwaldt, Arian Treffer'
-  s.email = 'ruby@nixis.de'
-  s.homepage = 'http://tech.lefedt.de/2010/3/annotation-based-security-for-rails'
-  s.add_dependency 'action_annotation', '>= 1.0.1'
-  s.add_dependency 'activesupport', '>= 2.3.5'
-  s.add_development_dependency 'rspec', '>= 1.2.0'
-  s.add_development_dependency 'mocha', '>= 0.9.8'
-  s.executables = ['annotation_security']
-  s.files = %w(CHANGELOG MIT-LICENSE README HOW-TO Rakefile) + Dir.glob("{bin,lib,spec,assets}/**/*")
-  s.require_path = "lib"
-  s.bindir = "bin"
-end
-
-Rake::GemPackageTask.new(spec) do |p|
-  p.gem_spec = spec
-  p.need_tar = true
-  p.need_zip = true
-end
-
-Rake::RDocTask.new do |rdoc|
-  files = ['README', 'MIT-LICENSE', 'CHANGELOG', 'HOW-TO', 'lib/**/*.rb']
-  rdoc.rdoc_files.add(files)
-  rdoc.main = "README" # page to start on
-  rdoc.title = "Annotation Security Docs"
-  rdoc.rdoc_dir = 'doc' # rdoc output folder
-  rdoc.options << '--line-numbers'
-end
-
-Spec::Rake::SpecTask.new do |t|
-  t.spec_files = FileList['spec/**/*_spec.rb']
+require 'rubygems'
+require 'rubygems/package_task'
+
+require 'rake'
+require 'rake/clean'
+
+require 'rdoc/task'
+
+require 'rspec/core/rake_task'
+
+require File.dirname(__FILE__) + '/lib/annotation_security/version'
+
+module RakeFileUtils
+  extend Rake::FileUtilsExt
+end
+
+spec = Gem::Specification.new do |s|
+  s.name = 'annotation_security'
+  s.version = AnnotationSecurity::Version
+  s.has_rdoc = true
+  s.extra_rdoc_files = ['README.md', 'LICENSE', 'CHANGELOG.md', 'HOW-TO.md']
+  s.summary = 'A role based security model for rails applications with ' +
+              'descriptive definitions and automated evaluation.'
+  s.description =
+    'AnnotationSecurity provides a role based security model with automated ' +
+    'rule evaluation for Ruby on Rails. It allows you to define user-resource-'+
+    'relations and rights in separate files, keeping your controllers and ' +
+    'views free from any security logic. See the gem\'s homepage for an ' +
+    'example.'
+  s.author = 'Nico Rehwaldt, Arian Treffer'
+  s.email = 'ruby@nixis.de'
+  s.homepage = 'http://github.com/Nikku/annotation_security'
+  s.add_dependency 'action_annotation', '>= 1.0.1'
+  s.add_dependency 'activesupport', '>= 2.3.18'
+  s.add_development_dependency 'rspec', '>= 1.3.2'
+  s.add_development_dependency 'mocha', '>= 0.9.8'
+  s.executables = ['annotation_security']
+  s.files = %w(CHANGELOG.md LICENSE README.md HOW-TO.md Rakefile) + Dir.glob("{bin,lib,spec,assets}/**/*")
+  s.require_path = "lib"
+  s.bindir = "bin"
+end
+
+desc "Create rdoc documentation"
+Rake::RDocTask.new do |rdoc|
+  files = ['README.md', 'LICENSE', 'CHANGELOG.md', 'HOW-TO.md', 'lib/**/*.rb']
+  rdoc.rdoc_files.add(files)
+  rdoc.main = "README.md" # page to start on
+  rdoc.title = "Annotation Security Docs"
+  rdoc.rdoc_dir = 'doc' # rdoc output folder
+  rdoc.options << '--line-numbers'
+end
+
+desc "Run rspec tests"
+RSpec::Core::RakeTask.new do |t|
+  t.rspec_opts = ["-c", "-f progress", "-r ./spec/spec_helper.rb"]
+  t.pattern = 'spec/**/*_spec.rb'
+end
+
+desc "Package library as gem"
+Gem::PackageTask.new(spec) do |pkg|
+  pkg.need_zip = true
+  pkg.need_tar = true
 end

data/assets/app/helpers/annotation_security_helper.rb

@@ -1,9 +1,9 @@
-#
-# = app/helpers/annotation_security_helper.rb
-#
-# This helper provides some useful view methods to be used in conjunction with
-# the plugin. See AnnotationSecurity::Helper for documentation.
-#
-module AnnotationSecurityHelper
-  include AnnotationSecurity::Helper
+#
+# = app/helpers/annotation_security_helper.rb
+#
+# This helper provides some useful view methods to be used in conjunction with
+# the plugin. See AnnotationSecurity::Helper for documentation.
+#
+module AnnotationSecurityHelper
+  include AnnotationSecurity::Helper
 end

data/assets/config/initializers/annotation_security.rb

@@ -1,12 +1,12 @@
-#
-# = config/initializers/annotation_security.rb
-#
-# Sets up files under <tt>config/security</tt> which hold
-# the security configuration.
-
-#
-# Add your own files here if they should also be loaded.
-#
-AnnotationSecurity.load_relations('relations')
-AnnotationSecurity.load_rights('rights')
+#
+# = config/initializers/annotation_security.rb
+#
+# Sets up files under <tt>config/security</tt> which hold
+# the security configuration.
+
+#
+# Add your own files here if they should also be loaded.
+#
+AnnotationSecurity.load_relations('relations')
+AnnotationSecurity.load_rights('rights')
 # AnnotationSecurity.load_rights('rights', 'rb) # loads rights from a ruby file

data/assets/config/security/relations.rb

@@ -1,20 +1,20 @@
-AnnotationSecurity.define_relations do
-
-  # All relations are defined in the context of a resource.
-  # The block should return true iif the user has this relations.
-
-#  all_resources do
-#    administrator(:system, :is => :administrator)
-#    owner_or_admin(:pretest){ owner or administrator }
-#    owner(:system) { |user| user.status == :registered }
-#  end
-
-#  resource :album do
-#    owner { |user, album| album.owner == user }
-#  end
-
-#  resource :picture do
-#    owner "if owner: album"
-#  end
-
-end
+AnnotationSecurity.define_relations do
+
+  # All relations are defined in the context of a resource.
+  # The block should return true iif the user has this relations.
+
+#  all_resources do
+#    administrator(:system, :is => :administrator)
+#    owner_or_admin(:pretest){ owner or administrator }
+#    owner(:system) { |user| user.status == :registered }
+#  end
+
+#  resource :album do
+#    owner { |user, album| album.owner == user }
+#  end
+
+#  resource :picture do
+#    owner "if owner: album"
+#  end
+
+end

data/assets/vendor/plugins/annotation_security/init.rb

@@ -1,14 +1,14 @@
-#
-# = init.rb
-#
-# This file will be copied to a rails apps `vendors/plugins/annotation_security`
-# directory if the annotation_security gem is installed into a rails app
-# via `annosec --rails`. It will be invoked by the rails app during startup an
-# loads the security layer.
-#
-
-require "annotation_security"
-
-# Initialize security layer for rails root
-puts "Initializing AnnotationSecurity security layer"
+#
+# = init.rb
+#
+# This file will be copied to a rails apps `vendors/plugins/annotation_security`
+# directory if the annotation_security gem is installed into a rails app
+# via `annosec --rails`. It will be invoked by the rails app during startup an
+# loads the security layer.
+#
+
+require "annotation_security"
+
+# Initialize security layer for rails root
+puts "Initializing AnnotationSecurity security layer"
 AnnotationSecurity::init_rails(binding)

data/bin/annotation_security

@@ -1,8 +1,8 @@
-#!/usr/bin/env ruby
-# The command line to install .
-
-$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
-
-require "annotation_security/exec"
-
+#!/usr/bin/env ruby
+# The command line to install .
+
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+
+require "annotation_security/exec"
+
 AnnotationSecurity::Exec::RailsInstaller.new(ARGV).parse!