eaco 0.5.0

data/lib/eaco/cucumber/world.rb

@@ -0,0 +1,136 @@
+module Eaco
+  module Cucumber
+
+    ##
+    # The world in which scenarios are run. This is a story and an example,
+    # real-world data model that can be effectively protected by Eaco.
+    #
+    # But +before { some :art }+
+    #
+    # == AYANAMI REI
+    #                                            __.-"..--,__
+    #                                       __..---"  | _|    "-_\
+    #                                __.---"          | V|::.-"-._D
+    #                           _--"".-.._   ,,::::::'"\/""'-:-:/
+    #                      _.-""::_:_:::::'-8b---"            "'
+    #                   .-/  ::::<  |\::::::"\
+    #                   \/:::/::::'\\ |:::b::\
+    #                   /|::/:::/::::-::b:%b:\|
+    #                    \/::::d:|8:::b:"%%%%%\
+    #                    |\:b:dP:d.:::%%%%%"""-,
+    #                     \:\.V-/ _\b%P_   /  .-._
+    #                     '|T\   "%j d:::--\.(    "-.
+    #                     ::d<   -" d%|:::do%P"-:.   "-,
+    #                     |:I _    /%%%o::o8P    "\.    "\
+    #                      \8b     d%%%%%%P""-._ _ \::.    \
+    #                      \%%8  _./Y%%P/      .::'-oMMo    )
+    #                        H"'|V  |  A:::...:odMMMMMM(  ./
+    #                        H /_.--"JMMMMbo:d##########b/
+    #                     .-'o      dMMMMMMMMMMMMMMP""
+    #                   /" /       YMMMMMMMMM|
+    #                 /   .   .    "MMMMMMMM/
+    #                 :..::..:::..  MMMMMMM:|
+    #                  \:/ \::::::::JMMMP":/
+    #                   :Ao ':__.-'MMMP:::Y
+    #                   dMM"./:::::::::-.Y
+    #                  _|b::od8::/:YM::/
+    #                  I HMMMP::/:/"Y/"
+    #                   \'""'  '':|
+    #                    |    -::::\
+    #                    |  :-._ '::\
+    #                    |,.|    \ _:"o
+    #                    | d" /   " \_:\.
+    #                    ".Y. \       \::\
+    #                     \ \  \      MM\:Y
+    #                      Y \  |     MM \:b
+    #                      >\ Y      .MM  MM
+    #                      .IY L_    MP'  MP
+    #                      |  \:|   JM   JP
+    #                      |  :\|   MP   MM
+    #                      |  :::  JM'  JP|
+    #                      |  ':' JP   JM |
+    #                      L   : JP    MP |
+    #                      0   | Y    JM  |
+    #                      0   |     JP"  |
+    #                      0   |    JP    |
+    #                      m   |   JP     #
+    #                      I   |  JM"     Y
+    #                      l   |  MP     :"
+    #                      |\  :-       :|
+    #                      | | '.\      :|
+    #                      | | "| \     :|
+    #                       \    \ \    :|
+    #                       |  |  | \   :|
+    #                       |  |  |   \ :|
+    #                       |   \ \    | '.
+    #                       |    |:\   | :|
+    #                       \    |::\..|  :\
+    #                        ". /::::::'  :||
+    #                          :|::/:::|  /:\
+    #                          | \/::|: \' ::|
+    #                          |  :::||    ::|
+    #                          |   ::||    ::|
+    #                          |   ::||    ::|
+    #                          |   ::||    ::|
+    #                          |   ': |    .:|
+    #                          |    : |    :|
+    #                          |    : |    :|
+    #                          |    :||   .:|
+    #                          |   ::\   .:|
+    #                         |    :::  .::|
+    #                        /     ::|  :::|
+    #                     __/     .::|   ':|
+    #            ...----""        ::/     ::
+    #           /m_  AMm          '/     .:::
+    #           ""MmmMMM#mmMMMMMMM"     .:::m
+    #              """YMMM""""""P        ':mMI
+    #                       _'           _MMMM
+    #                   _.-"  mm   mMMMMMMMM"
+    #                  /      MMMMMMM""
+    #                  mmmmmmMMMM"
+    #                                   ch1x0r
+    #
+    #         http://ascii.co.uk/art/anime
+    #
+    # = Scenario
+    #
+    # In this imaginary world we are  N E R V, a Top Secret organization that
+    # handles very confidential documents. Some users can read them, some can
+    # edit them, and very few bosses can destroy them.
+    #
+    # The organization employs internal staff and employs consultants.  Staff
+    # members have official positions in the organization hierarchy, and they
+    # belong to units within departments. They have the big picture.
+    #
+    # Consultants, on the other hand, come and go, and work on small parts of
+    # the documents, for specific purposes. They do not have the big picture.
+    #
+    # Departments own the documents, not people. Documents are of interest of
+    # departments, sometimes they should be accessed by the whole house, some
+    # other time only few selected users, some times two specific departments
+    # or some units.
+    #
+    # Either way, most of the time, access is granted to who owns a peculiar
+    # authority within the organization and not to a specific person. People
+    # may change, authorities and rules change less often.
+    #
+    # = Mapping Eaco concepts
+    #
+    # The +Document+ is a {Eaco::Resource}
+    #
+    # Each instance of a +Document+ has an {Eaco::ACL} +.acl+ attribute.
+    #
+    # The +:reader+, +:editor+ and +:owner+ are Roles on the Document
+    # resource, and each role is granted a Permission.
+    #
+    # The User is a {Eaco::Actor}.
+    #
+    # Having an user account is the {Eaco::Designator} of type +:user+.
+    # Occupying an official position is the Designator of type +:position+.
+    # Belonging to a department is the Designator of type +:department+
+    #
+    class World
+    end
+
+  end
+end

data/lib/eaco/designator.rb

@@ -0,0 +1,264 @@
+module Eaco
+
+  ##
+  # A Designator characterizes an Actor.
+  #
+  # Example: an User Actor is uniquely identified by its numerical +id+, as
+  # such we can define an +user+ designator that designs User 42 as +user:42+.
+  #
+  # The same User also could belong to the group +frobber+, uniquely
+  # identified by its name. We can then define a +group+ designator that would
+  # design the same User as +group:frobber+.
+  #
+  # In ACLs designators are given roles, and the intersection between the
+  # designators of an Actor and the ones defined in the ACL gives the role of
+  # the Actor for the Resource that the ACL secures.
+  #
+  # Designators for actors are defined through the DSL, see {DSL::Actor}
+  #
+  # @see ACL
+  # @see Actor
+  #
+  class Designator < String
+    class << self
+
+      ##
+      # Instantiate a designator of the given +type+ with the given +value+.
+      #
+      # Example:
+      #
+      #   >> Designator.make('user', 42)
+      #   => #<Designator(User) value:42>
+      #
+      # @param type [String] the designator type (e.g. +user+)
+      # @param value [String] the designator value. It will be stringified using +.to_s+.
+      #
+      # @return [Designator]
+      #
+      def make(type, value)
+        Eaco::DSL::Actor.find_designator(type).new(value)
+      end
+
+      ##
+      # Parses a Designator string representation and instantiates a new
+      # Designator instance from it.
+      #
+      #   >> Designator.parse('user:42')
+      #   => #<Designator(User) value:42>
+      #
+      # @param string [String] the designator string representation.
+      #
+      # @return [Designator]
+      #
+      def parse(string)
+        return string if string.is_a?(Designator)
+        make(*string.split(':', 2))
+      end
+
+      ##
+      # Resolves one or more designators into the target actors.
+      #
+      # @param designators [Array] designator string representations.
+      #
+      # @return [Array] resolved actors, application-dependant.
+      #
+      def resolve(designators)
+        Array.new(designators||[]).inject([]) {|ret, d| ret.concat parse(d).resolve}
+      end
+
+      ##
+      # Sets up the designator implementation with the given options.
+      # Currently:
+      #
+      # * +:from+ - defines the method to call on the Actor to obtain the unique
+      #             IDs for this Designator class.
+      #
+      # Example configuration:
+      #
+      #   actor User do
+      #     designators do
+      #       user  from: :id
+      #       group from: :group_ids
+      #     end
+      #   end
+      #
+      # This method is called from the DSL.
+      #
+      # @see DSL::Actor::Designators
+      # @see DSL::Actor::Designators#define_designator
+      #
+      def configure!(options)
+        @method = options.fetch(:from)
+        self
+
+      rescue KeyError
+        raise Malformed, "The designator option :from is required"
+      end
+
+      ##
+      # Harvests valid designators for the given Actor.
+      #
+      # It calls the +@method+ defined through the +:from+ option passed when
+      # configuring the designators (see {Designator.configure!}).
+      #
+      # @param actor [Actor]
+      #
+      # @return [Array] an array of Designator objects the Actor owns.
+      #
+      # @see Actor
+      #
+      def harvest(actor)
+        Array.new(actor.send(@method)||[]).map {|value| new(value) }
+      end
+
+      ##
+      # Sets this Designator label to the given value.
+      #
+      # Example:
+      #
+      #   class User::Designators::Group < Eaco::Designator
+      #     label "Active Directory Group"
+      #   end
+      #
+      # @param value [String] the designator label
+      #
+      # @return [String] the configured label
+      #
+      def label(value = nil)
+        @label = value if value
+        @label ||= designator_name
+      end
+
+      ##
+      # Returns this class' demodulized name
+      #
+      def designator_name
+        self.name.split('::').last
+      end
+
+      ##
+      # Returns the designator type.
+      #
+      # The type symbol is derived from the class name, on the other way
+      # around, the {DSL} looks up designator implementation classes from the
+      # designator type symbol.
+      #
+      # Example:
+      #
+      #   >> User::Designators::Group.id
+      #   => :group
+      #
+      # @return [Symbol]
+      #
+      # @see DSL::Actor::Designators#implementation_for
+      #
+      def id
+        @_id ||= self.designator_name.gsub(/([a-z])?([A-Z])/) do |x|
+          [$1, $2.downcase].compact.join '_'
+        end.intern
+      end
+      alias type id
+
+      ##
+      # Searches designator definitions using the given query.
+      #
+      # To be implemented by derived classes. E.g. for a "User" designator
+      # this would return your own User instances that you may want to display
+      # in a typeahead menu, for your Enterprise authorization management
+      # UI... :-)
+      #
+      # @raise [NotImplementedError]
+      #
+      def search(query)
+        raise NotImplementedError
+      end
+    end
+
+    ##
+    # Initializes the designator with the given value. The string
+    # representation is then calculated by concatenating the type and the
+    # given value.
+    #
+    # An optional instance can be attached, if you use to pass around
+    # designators in your app.
+    #
+    # @param value [String] the unique ID valid in this designator namespace
+    # @param instance [Actor] optional Actor instance
+    #
+    def initialize(value, instance = nil)
+      @value, @instance = value, instance
+      super([ self.class.id, value ].join(':'))
+    end
+
+    # This designator unique ID in the namespace of the designator type.
+    attr_reader :value
+
+    # The instance given to {Designator#initialize}
+    attr_reader :instance
+
+    ##
+    # Should return an extended description for this designator. You can then
+    # use this to display it in your application.
+    #
+    # E.g. for an "User" designator this would be the user name, for a "Group"
+    # designator this would be the group name.
+    #
+    # @param style [Symbol] the description style. {#as_json} uses +:full+,
+    #        but you are free to define whatever styles you do see fit.
+    #
+    # @return [String] the description
+    #
+    def describe(style = nil)
+      nil
+    end
+
+    ##
+    # Translates this designator to concrete Actor instances in your
+    # application. To be implemented by derived classes.
+    #
+    # @raise [NotImplementedError]
+    #
+    def resolve
+      raise NotImplementedError
+    end
+
+    ##
+    # Converts this designator to an Hash for +.to_json+ to work.
+    #
+    # @param options [Ignored]
+    #
+    # @return [Hash]
+    #
+    def as_json(options = nil)
+      { :value => to_s, :label => describe(:full) }
+    end
+
+    ##
+    # Pretty prints the designator in your console.
+    #
+    # @return [String]
+    #
+    def inspect
+      %[#<Designator(#{self.class.designator_name}) value:#{value.inspect}>]
+    end
+
+    ##
+    # @return [String] the designator's class label.
+    #
+    # @see Designator.label
+    #
+    def label
+      self.class.label
+    end
+
+    ##
+    # @return [Symbol] the designator's class type.
+    #
+    # @see Designator.type
+    #
+    def type
+      self.class.type
+    end
+  end
+
+end

data/lib/eaco/dsl.rb

@@ -0,0 +1,40 @@
+module Eaco
+
+  ##
+  # Eaco DSL entry point.
+  #
+  # @see DSL::Resource
+  # @see DSL::Actor
+  # @see DSL::ACL
+  #
+  module DSL
+    extend self # Oh the irony.
+
+    autoload :Base,     'eaco/dsl/base'
+
+    autoload :ACL,      'eaco/dsl/acl'
+    autoload :Actor,    'eaco/dsl/actor'
+    autoload :Resource, 'eaco/dsl/resource'
+
+    ##
+    # Entry point for the {Resource} authorization definition.
+    #
+    # @see DSL::Resource
+    # @see DSL::ACL
+    #
+    def authorize(resource_class, options = {}, &block)
+      DSL::Resource.eval(resource_class, options, &block)
+      DSL::ACL.eval(resource_class, options)
+    end
+
+    ##
+    # Entry point for the {Actor} designators definition.
+    #
+    # @see DSL::Actor
+    #
+    def actor(actor_class, options = {}, &block)
+      DSL::Actor.eval(actor_class, options, &block)
+    end
+  end
+
+end

data/lib/eaco/dsl/acl.rb

@@ -0,0 +1,163 @@
+require 'eaco/dsl/base'
+
+module Eaco
+  module DSL
+
+    ##
+    # Block-less DSL to set up the {ACL} machinery onto an authorized {Resource}.
+    #
+    # * Defines an {ACL} subclass in the Resource namespace
+    # * Defines syntactic sugar on the ACL to easily retrieve {Actor}s with a
+    #   specific Role
+    # * Installs {ACL} objects persistance for the supported ORMs
+    # * Installs the authorized collection extraction strategy +.accessible_by+
+    #
+    class ACL < Base
+
+      ##
+      # Performs ACL setup on the target Resource class.
+      #
+      # @see #define_acl_subclass
+      # @see #define_role_getters
+      # @see #install_persistance
+      #
+      def initialize(*)
+        super
+
+        define_acl_subclass
+        define_role_getters
+        install_persistance
+      end
+
+      private
+
+      ##
+      # Creates the ACL constant on the target, inheriting from {Eaco::ACL}.
+      # Removes if it is already set, so that a reload of the authorization
+      # rules refreshes also these constants.
+      #
+      # The ACL subclass can be retrieved using the +.acl+ singleton method
+      # on the {Resource} class.
+      #
+      # @return [void]
+      #
+      def define_acl_subclass
+        target_eval do
+          remove_const(:ACL) if const_defined?(:ACL)
+
+          Class.new(Eaco::ACL).tap do |acl_class|
+            define_singleton_method(:acl) { acl_class }
+            const_set(:ACL, acl_class)
+          end
+        end
+      end
+
+      ##
+      # Define getter methods on the ACL for each role, syntactic sugar
+      # for calling {ACL#find_by_role}.
+      #
+      # Example:
+      #
+      # If a +reader+ role is defined, allows doing +resource.acl.readers+
+      # and returns all the designators having the +reader+ role set.
+      #
+      # @return [void]
+      #
+      def define_role_getters
+        roles = self.target.roles
+
+        target.acl.instance_eval do
+          roles.each do |role|
+            define_method(role.to_s.pluralize) { find_by_role(role) }
+          end
+        end
+      end
+
+      ##
+      # Sets up the persistance layer for ACLs (+#acl+ and +#acl=+) and the
+      # authorized collection extraction strategy (+.accessible_by+).
+      #
+      # All these APIs can be implemented directly in your models, as
+      # long as the +acl+ accessor accepts and returns the model's ACL
+      # subclass (see {.define_acl_subclass}); and the +.accessible_by+
+      # returns an +Enumerable+ collection.
+      #
+      # See each adapter for the details of the extraction strategies
+      # they provide.
+      #
+      # @return [void]
+      #
+      def install_persistance
+        if adapter
+          target.send(:include, adapter)
+          install_authorized_collection_strategy
+
+        elsif target.respond_to?(:acl) && target.respond_to?(:acl=)
+          raise Malformed, <<-EOF
+            Don't know how to persist ACLs using <#{target}>'s ORM
+            (identified as <#{orm}>). Please define an `acl' instance
+            accessor on <#{target}> that accepts and returns a <#{target.acl}>.
+          EOF
+        end
+
+        unless target.respond_to?(:accessible_by)
+          strategies = adapter ? adapter.strategies.keys : []
+
+          raise Malformed, <<-EOF
+            Don't know how to look up authorized records on <#{target}>'s
+            ORM (identified as <#{orm}>). To authorize <#{target}>
+
+            #{ if strategies.size > 0
+              "either use one of the available strategies: #{strategies.join(', ')} or"
+            end }
+
+            please define your own #{target}.accessible_by method.
+            You may at one point want to move this in a new strategy,
+            and send a pull request :-).
+          EOF
+        end
+      end
+
+      ##
+      # Looks up the authorized collection strategy within the Adapter,
+      # using the +:using+ option given to the +authorize+ Resource DSL
+      #
+      # @see DSL::Resource
+      #
+      # @return [void]
+      #
+      def install_authorized_collection_strategy
+        if adapter && (strategy = adapter.strategies[ options.fetch(:using, nil) ])
+          target.extend strategy
+        end
+      end
+
+      ##
+      # Tries to identify which ORM adapter to use for the +target+ class.
+      #
+      # @return [Class] the adapter implementation or nil if not available.
+      #
+      def adapter
+        { 'ActiveRecord::Base'     => Eaco::Adapters::ActiveRecord,
+          'CouchRest::Model::Base' => Eaco::Adapters::CouchrestModel,
+        }.fetch(orm.name, nil)
+      end
+
+      ##
+      # Tries to naively identify which ORM the target model is using.
+      #
+      # TODO support more stuff
+      #
+      # @return [Class] the ORM base class.
+      #
+      def orm
+        if target.respond_to?(:base_class)
+          target.base_class.superclass # Active Record
+        else
+          target.superclass # Naive
+        end
+      end
+    end
+
+  end
+end