eaco 0.5.0

data/features/rails_integration.feature

@@ -0,0 +1,10 @@
+Feature: Rails integration
+  The framework should play nice with the most recent major Rails version
+
+  Background:
+    Given I am connected to the database
+    And I have a schema defined
+
+  Scenario:
+    When I authorize the Document model
+    Then I should be able to set an ACL on it

data/features/step_definitions/database.rb

@@ -0,0 +1,7 @@
+Given(/I am connected to the database/) do
+  Eaco::Cucumber::ActiveRecord.connect!
+end
+
+Given(/I have a schema defined/) do
+  Eaco::Cucumber::ActiveRecord.define_schema!
+end

data/features/step_definitions/resource_authorization.rb

@@ -0,0 +1,15 @@
+When(/I authorize the (\w+) model/) do |model_name|
+  @model = Eaco::Cucumber::ActiveRecord.const_get(model_name)
+
+  Eaco::DSL.authorize @model, using: :pg_jsonb
+end
+
+Then(/I should be able to set an ACL on it/) do
+  instance = @model.new
+
+  instance.acl = {foo: :bar}
+  instance.save!
+  instance = @model.find(instance.id)
+
+  instance.acl == {foo: :bar} && instance.acl.class.kind_of?(Eaco::ACL)
+end

data/features/support/env.rb

@@ -0,0 +1,9 @@
+require 'bundler/setup'
+require 'byebug'
+require 'eaco'
+require 'eaco/cucumber'
+
+# Create a whole new world
+World do
+  Eaco::Cucumber::World.new
+end

data/gemfiles/rails_3.2.gemfile

@@ -0,0 +1,9 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rails", "~> 3.2.0"
+gem "pg"
+gem "activerecord-postgres-json", :require => false
+
+gemspec :path => "../"

data/gemfiles/rails_4.0.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rails", "~> 4.0.0"
+gem "pg"
+
+gemspec :path => "../"

data/gemfiles/rails_4.1.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rails", "~> 4.1.0"
+gem "pg"
+
+gemspec :path => "../"

data/gemfiles/rails_4.2.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rails", "~> 4.2.0"
+gem "pg"
+
+gemspec :path => "../"

data/lib/eaco.rb

@@ -0,0 +1,93 @@
+require 'eaco/error'
+require 'eaco/version'
+
+if defined? Rails
+  require 'eaco/railtie'
+end
+
+require 'pathname'
+
+############################################################################
+#
+# Welcome to Eaco!
+#
+# Eaco is a full-fledged authorization framework for Ruby that allows you to
+# describe which actions are allowed on your resources, how to identify your
+# users as having a particular privilege and which privileges are granted to
+# a specific resource through the usage of ACLs.
+#
+module Eaco
+  autoload :ACL,        'eaco/acl'
+  autoload :Actor,      'eaco/actor'
+  autoload :Adapters,   'eaco/adapters'
+  autoload :DSL,        'eaco/dsl'
+  autoload :Designator, 'eaco/designator'
+  autoload :Resource,   'eaco/resource'
+
+  # The location of the default rules file
+  DEFAULT_RULES = Pathname('./config/authorization.rb')
+
+  ##
+  # Parses and evaluates the authorization rules from the {DEFAULT_RULES}.
+  #
+  # The authorization rules define all the authorization framework behaviour
+  # through the {DSL}
+  #
+  # @return (see .eval!)
+  #
+  def self.parse_default_rules_file!
+    parse_rules! DEFAULT_RULES
+  end
+
+  ##
+  # Parses the given +rules+ file.
+  #
+  # @param rules [Pathname]
+  #
+  # @return (see .eval!)
+  #
+  # @raise [Malformed] if the +rules+ file does not exist.
+  #
+  def self.parse_rules!(rules)
+    unless rules.exist?
+      path = rules.realpath rescue rules.to_s
+      raise Malformed, "Please create #{path} with Eaco authorization rules"
+    end
+
+    eval! rules.read, rules.realpath.to_s
+  end
+
+  ##
+  # Evaluates the given authorization rules +source+, orignally found on
+  # +path+.
+  #
+  # @param source [String] {DSL} source code
+  # @param path [String] Source code origin, for better backtraces.
+  #
+  # @return true
+  #
+  # @raise [Error] if something goes wrong while evaluating the DSL.
+  #
+  # @see DSL
+  #
+  def self.eval!(source, path)
+    DSL.send :eval, source, nil, path, 1
+
+    true
+  rescue => e
+    raise Error, <<-EOF
+
+=== EACO === Error while evaluating rules
+
+#{e.message}
+
+ +--------- -- -
+ | #{e.backtrace.join("\n | ")}
+ +-
+
+=== EACO ===
+
+    EOF
+  end
+
+end

data/lib/eaco/acl.rb

@@ -0,0 +1,206 @@
+module Eaco
+
+  ##
+  # An ACL is an Hash whose keys are Designator string representations and
+  # values are the role symbols defined in the Resource permissions
+  # configuration.
+  #
+  # Example:
+  #
+  #   authorize Document do
+  #     roles :reader, :editor
+  #   end
+  #
+  # @see Actor
+  # @see Resource
+  #
+  class ACL < Hash
+
+    ##
+    # Builds a new ACL object from the given Hash representation with strings
+    # as keys and values.
+    #
+    # @param definition [Hash] the ACL hash
+    #
+    # @return [ACL] this ACL
+    #
+    def initialize(definition = {})
+      definition.each do |designator, role|
+        self[designator] = role.intern
+      end
+    end
+
+    ##
+    # Gives the given Designator access as the given +role+.
+    #
+    # @param role [Symbol] the role to grant
+    # @param designator [Variadic] (see {#identify})
+    #
+    # @return [ACL] this ACL
+    #
+    def add(role, *designator)
+      identify(*designator).each do |key|
+        self[key] = role
+      end
+
+      self
+    end
+
+    ##
+    # Removes access from the given Designator.
+    #
+    # @param designator [Variadic] (see {#identify})
+    #
+    # @return [ACL] this ACL
+    #
+    # @see Designator
+    #
+    def del(*designator)
+      identify(*designator).each do |key|
+        self.delete(key)
+      end
+
+      self
+    end
+
+    ##
+    # @param name [Symbol] The role name
+    #
+    # @return [Set] A set of Designators having the given +role+.
+    #
+    # @see Designator
+    # @see Resource
+    #
+    def find_by_role(name)
+      self.inject(Set.new) do |ret, (designator, role)|
+        ret.tap { ret.add Designator.parse(designator) if role == name }
+      end
+    end
+
+    ##
+    # @return [Set] all Designators in the ACL, regardless of their role.
+    #
+    def all
+      self.inject(Set.new) do |ret, (designator,_)|
+        ret.add Designator.parse(designator)
+      end
+    end
+
+    ##
+    # Gets a map of Actors in the ACL having the given +role+.
+    #
+    # This is a useful starting point for an Enterprise summary page of who is
+    # granted to access a resource. Given that actor resolution is dynamic and
+    # handled by the application's Designators implementation, you can rely on
+    # your internal organigram APIs to resolve actual people out of positions,
+    # groups, department of assignment, etc.
+    #
+    # @param name [Symbol] The role name
+    #
+    # @return [Hash] keyed by designator with Set of Actors as values
+    #
+    # @see Actor
+    # @see Resource
+    #
+    def designators_map_for_role(name)
+      find_by_role(name).inject({}) do |ret, designator|
+        actors = designator.resolve
+
+        ret.tap do
+          ret[designator] ||= Set.new
+          ret[designator].merge Array.new(actors)
+        end
+      end
+    end
+
+    ##
+    # @param name [Symbol] the role name
+    #
+    # @return [Set] Actors having the given +role+.
+    #
+    # @see Actor
+    # @see Resource
+    #
+    def actors_by_role(name)
+      find_by_role(name).inject(Set.new) do |set, designator|
+        set |= Array.new(designator.resolve)
+      end.to_a
+    end
+
+    ##
+    # Pretty prints this ACL in your console.
+    #
+    def inspect
+      "#<#{self.class.name}: #{super}>"
+    end
+    alias pretty_print_inspect inspect
+
+    ##
+    # Pretty print for +pry+.
+    #
+    def pretty_inspect
+      "#{self.class.name}\n#{super}"
+    end
+
+    protected
+
+    ##
+    # There are three ways of specifying designators:
+    #
+    # * Passing an +Designator+ instance obtained from somewhere else:
+    #
+    #     >> designator
+    #     => #<Designator(User) value:42>
+    #
+    #     >> resource.acl.add :reader, designator
+    #     => #<Resource::ACL {"user:42"=>:reader}>
+    #
+    # * Passing a designator type and an unique ID valid in the designator's
+    #   namespace:
+    #
+    #     >> resource.acl.add :reader, :user, 42
+    #     => #<Resource::ACL {"user:42"=>:reader}>
+    #
+    # * Passing a designator type and an Actor instance, will add all
+    #   designators of the given type owned by the Actor.
+    #
+    #     >> actor
+    #     => #<User id:42 name:"Ethan Siegel">
+    #
+    #     >> actor.designators
+    #     => #<Set:{
+    #      |   #<Designator(User) value:42>,
+    #      |   #<Designator(Group) value:"astrophysicists">,
+    #      |   #<Designator(Group) value:"medium bloggers">
+    #      | }>
+    #
+    #     >> resource.acl.add :editor, :group, actor
+    #     => #<Resource::ACL {
+    #      |   "group:astrophysicists"=>:editor,
+    #      |   "group:medium bloggers"=>:editor
+    #      | }
+    #
+    # @param designator [Designator] the designator to grant
+    # @param actor_or_id [Actor] or [String] the actor
+    #
+    def identify(designator, actor_or_id = nil)
+      if designator.is_a?(Eaco::Designator)
+        [designator]
+
+      elsif designator && actor_or_id.respond_to?(:designators)
+        actor_or_id.designators.select {|d| d.type == designator}
+
+      elsif designator.is_a?(Symbol)
+        [Eaco::Designator.make(designator, actor_or_id)]
+
+      else
+        raise Error, <<-EOF
+          Cannot infer designator
+          from #{designator.inspect}
+          and #{actor_or_id.inspect}
+        EOF
+      end
+    end
+  end
+
+end

data/lib/eaco/actor.rb

@@ -0,0 +1,86 @@
+module Eaco
+
+  ##
+  # An Actor is an entity whose access to Resources is discretionary,
+  # depending on the Role this actor has in the ACL.
+  #
+  # The role of this +Actor+ is calculated from the +Designator+ that
+  # the actor instance has, and the +ACL+ instance attached to the
+  # +Resource+.
+  #
+  # @see ACL
+  # @see Resource
+  # @see DSL::Actor
+  #
+  module Actor
+
+    # @private
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    ##
+    # Singleton methods added to Actor classes.
+    #
+    module ClassMethods
+      ##
+      # The designators implementations defined for this Actor as an Hash
+      # keyed by designator type symbol and with the concrete Designator
+      # implementations as values.
+      #
+      # @see DSL::Actor#initialize
+      #
+      def designators
+      end
+
+      ##
+      # The logic that evaluates whether an Actor instance is an admin.
+      #
+      # @see DSL::Actor#initialize
+      #
+      def admin_logic
+      end
+    end
+
+    ##
+    # @return [Set] the designators granted to this Actor.
+    #
+    # @see Designator
+    #
+    def designators
+      @_designators ||= Set.new.tap do |ret|
+        self.class.designators.each do |_, designator|
+          ret.merge designator.harvest(self)
+        end
+      end
+    end
+
+    ##
+    # Checks whether this Actor fulfills the admin logic.
+    #
+    # This logic is called by +Resource+ Adapters' +accessible_by+, that
+    # returns the full collection, and by {Resource#allows?}, that bypassess
+    # access checks always returning true.
+    #
+    # @return [Boolean] True or False if admin logic is defined, nil if not.
+    #
+    def is_admin?
+      return unless self.class.admin_logic
+
+      instance_exec(self, &self.class.admin_logic)
+    end
+
+    ##
+    # Checks wether the given Resource allows this Actor to perform the given action.
+    #
+    # @param action [Symbol] a valid action for this Resource (see {DSL::Resource})
+    # @param resource [Resource] an authorized resource
+    #
+    # @see Resource
+    #
+    def can?(action, resource)
+      resource.allows?(action, self)
+    end
+  end
+
+end