aker 3.0.0.pre

data/lib/aker/form/login_form_asset_provider.rb

@@ -0,0 +1,56 @@
+require 'aker/modes/support'
+require 'erb'
+require 'rack'
+
+module Aker::Form
+  ##
+  # Provides HTML and CSS for login forms.
+  #
+  # @author David Yip
+  module LoginFormAssetProvider
+    include Rack::Utils
+    include Aker::Rack::ConfigurationHelper
+
+    ##
+    # Where to look for HTML and CSS assets.
+    #
+    # This is currently hardcoded as `(aker gem root)/assets/aker/form`.
+    #
+    # @return [String] a directory path
+    def asset_root
+      File.expand_path(File.join(File.dirname(__FILE__),
+                                 %w(.. .. ..),
+                                 %w(assets aker form)))
+    end
+
+    ##
+    # Provides the HTML for the login form.
+    #
+    # This method expects to find a `login.html.erb` ERB template in
+    # {#asset_root}.  The ERB template is evaluated in an environment where
+    # a local variable named `script_name` is bound to the value of the
+    # `SCRIPT_NAME` Rack environment variable, which is useful for CSS and
+    # form action URL generation.
+    #
+    # @param env [Rack environment] a Rack environment
+    # @param [Hash] options rendering options
+    # @option options [Boolean] :login_failed If true, will render a failure message
+    # @option options [Boolean] :logged_out If true, will render a logout notification
+    # @option options [String] :username Text for the username field
+    # @option options [String] :url A URL to redirect to upon successful login
+    # @return [String] HTML data
+    def login_html(env, options = {})
+      login_base = env['SCRIPT_NAME'] + login_path(env)
+      template = File.read(File.join(asset_root, 'login.html.erb'))
+      ERB.new(template).result(binding)
+    end
+
+    ##
+    # Provides the CSS for the login form.
+    #
+    # @return [String] CSS data
+    def login_css
+      File.read(File.join(asset_root, 'login.css'))
+    end
+  end
+end

data/lib/aker/form/middleware/custom_view_login_responder.rb

@@ -0,0 +1,19 @@
+require 'aker'
+
+module Aker::Form::Middleware
+  ##
+  # Extends {LoginResponder} to allow the application to re-render the
+  # login form when using {CustomViewsMode}.
+  class CustomViewLoginResponder < LoginResponder
+    protected
+
+    def unauthenticated(env)
+      request = ::Rack::Request.new(env)
+
+      env['aker.form.login_failed'] = true
+      env['aker.form.username'] = request['username']
+
+      @app.call(env)
+    end
+  end
+end

data/lib/aker/form/middleware/login_renderer.rb

@@ -0,0 +1,72 @@
+require 'aker'
+
+module Aker::Form::Middleware
+  ##
+  # Rack middleware used by {Aker::Form::Mode} to render an HTML login
+  # form.
+  #
+  # This middleware implements half of the form login process.  The
+  # other half is implemented by {LoginResponder}.
+  #
+  # @author David Yip
+  class LoginRenderer
+    include Aker::Form::LoginFormAssetProvider
+    include Aker::Rack::ConfigurationHelper
+
+    ##
+    # Instantiates the middleware.
+    #
+    # @param app [Rack app] The Rack application on which this middleware
+    #   should be layered.
+    # @param login_path [String] the login path
+    def initialize(app)
+      @app = app
+    end
+
+    ##
+    # Rack entry point.
+    #
+    # `call` returns one of three responses, depending on the path and
+    # method.
+    #
+    # * If the method is GET and the path is `login_path`, `call` returns
+    #   an HTML form for submitting a username and password.
+    # * If the method is GET and the path is `login_path + "/login.css"`,
+    #   `call` returns the CSS for the aforementioned form.
+    # * Otherwise, `call` passes the request down through the Rack stack.
+    #
+    # @return a finished Rack response
+    def call(env)
+      case [env['REQUEST_METHOD'], env['PATH_INFO']]
+        when ['GET', login_path(env)];                provide_login_html(env)
+        when ['GET', login_path(env) + '/login.css']; provide_login_css
+        else                                          @app.call(env)
+      end
+    end
+
+    private
+
+    ##
+    # An HTML form for logging in.
+    #
+    # @param env the Rack environment
+    # @return a finished Rack response
+    def provide_login_html(env)
+      request = ::Rack::Request.new(env)
+
+      ::Rack::Response.new(
+        login_html(env, :url => request['url'], :session_expired => request['session_expired'])
+      ).finish
+    end
+
+    ##
+    # CSS for the form provided by {provide_login_html}.
+    #
+    # @return a finished Rack response
+    def provide_login_css
+      ::Rack::Response.new(login_css) do |resp|
+        resp['Content-Type'] = 'text/css'
+      end.finish
+    end
+  end
+end

data/lib/aker/form/middleware/login_responder.rb

@@ -0,0 +1,71 @@
+require 'aker'
+
+module Aker::Form::Middleware
+  ##
+  # Rack middleware used by {Aker::Form::Mode} that finishes login
+  # requests by rendering a "Login successful" message.
+  #
+  # This middleware implements half of the form login process.  The
+  # other half is implemented by {LoginRenderer}.
+  #
+  # @author David Yip
+  class LoginResponder
+    include Aker::Form::LoginFormAssetProvider
+    include Aker::Rack::ConfigurationHelper
+
+    ##
+    # Instantiates the middleware.
+    #
+    # @param app [Rack app] the Rack application on which this middleware
+    #                       should be layered
+    def initialize(app)
+      @app = app
+    end
+
+    ##
+    # Rack entry point.  Responds to a `POST` to the configured login
+    # path.
+    #
+    # If the user is authenticated and a URL is given in the `url`
+    # parameter, then this action will redirect to `url`.
+    #
+    # @param env the Rack environment
+    # @return a finished Rack response
+    def call(env)
+      case [env['REQUEST_METHOD'], env['PATH_INFO']]
+        when ['POST', login_path(env)]; respond(env)
+        else @app.call(env)
+      end
+    end
+
+    protected
+
+    def respond(env)
+      warden = env['warden']
+
+      if !warden.authenticated?
+        warden.custom_failure!
+        unauthenticated(env)
+      else
+        redirect_to_target(env)
+      end
+    end
+
+    def unauthenticated(env)
+      request = Rack::Request.new(env)
+      body = login_html(env,
+                        :login_failed => true,
+                        :username => request['username'],
+                        :url => request['url'])
+
+      ::Rack::Response.new(body, 401).finish
+    end
+
+    def redirect_to_target(env)
+      request = Rack::Request.new(env)
+      target = !(request['url'].blank?) ? request['url'] : request.env['SCRIPT_NAME'] + '/'
+
+      ::Rack::Response.new { |resp| resp.redirect(target) }.finish
+    end
+  end
+end

data/lib/aker/form/middleware/logout_responder.rb

@@ -0,0 +1,26 @@
+require 'aker'
+
+module Aker::Form::Middleware
+  class LogoutResponder
+    include Aker::Form::LoginFormAssetProvider
+    include Aker::Rack::ConfigurationHelper
+
+    def initialize(app)
+      @app = app
+    end
+
+    ##
+    # When given `GET` to the configured logout path, builds a Rack
+    # response containing the login form with a "you have been logged
+    # out" notification.  Otherwise, passes the response on.
+    #
+    # @return a finished Rack response
+    def call(env)
+      if env['REQUEST_METHOD'] == 'GET' && env['PATH_INFO'] == logout_path(env)
+        ::Rack::Response.new(login_html(env, :logged_out => true)).finish
+      else
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/aker/form/middleware.rb

@@ -0,0 +1,10 @@
+require 'aker'
+
+module Aker::Form
+  module Middleware
+    autoload :CustomViewLoginResponder, 'aker/form/middleware/custom_view_login_responder'
+    autoload :LogoutResponder,          'aker/form/middleware/logout_responder'
+    autoload :LoginRenderer,            'aker/form/middleware/login_renderer'
+    autoload :LoginResponder,           'aker/form/middleware/login_responder'
+  end
+end

data/lib/aker/form/mode.rb

@@ -0,0 +1,118 @@
+require 'aker'
+require 'uri'
+require 'rack'
+
+module Aker
+  module Form
+    ##
+    # An interactive mode that accepts a username and password POSTed from an
+    # HTML form.
+    #
+    # It expects the username in a `username` parameter and the unobfuscated
+    # password in a `password` parameter.
+    #
+    # By default, the form is rendered at and the credentials are
+    # received on '/login'; this can be overridden in the
+    # configuration like so:
+    #
+    #     Aker.configure {
+    #       rack_parameters :login_path => '/log-in-here'
+    #     }
+    #
+    # This mode also renders said HTML form if authentication
+    # fails. Rendering is handled by by {Middleware::LoginRenderer}.
+    #
+    # @author David Yip
+    class Mode < Aker::Modes::Base
+      include ::Rack::Utils
+      include Aker::Modes::Support::AttemptedPath
+
+      ##
+      # A key that refers to this mode; used for configuration convenience.
+      #
+      # @return [Symbol]
+      def self.key
+        :form
+      end
+
+      ##
+      # Appends the {Middleware::LoginResponder login responder} to its
+      # position in the Rack middleware stack.
+      def self.append_middleware(builder)
+        builder.use(Middleware::LoginResponder)
+        builder.use(Middleware::LogoutResponder)
+      end
+
+      ##
+      # Prepends the {Middleware::LoginRenderer login form renderer} to
+      # its position in the Rack middleware stack.
+      def self.prepend_middleware(builder)
+        builder.use(Middleware::LoginRenderer)
+      end
+
+      ##
+      # The type of credentials supplied by this mode.
+      #
+      # @return [Symbol]
+      def kind
+        :user
+      end
+
+      ##
+      # Extracts username and password from request parameters.
+      #
+      # @return [Array<String>] username and password, username (if password
+      #                         missing), or an empty array
+      def credentials
+        [request['username'], request['password']].compact
+      end
+
+      ##
+      # Returns true if username and password are present, false otherwise.
+      def valid?
+        credentials.length == 2
+      end
+
+      ##
+      # The absolute URL for the login form.
+      #
+      # @return [String]
+      def login_url
+        uri = URI.parse(request.url)
+        uri.path = env['SCRIPT_NAME'] + login_path(configuration)
+        uri.to_s
+      end
+
+      ##
+      # Builds a Rack response that redirects to the login form.
+      #
+      # @return [Rack::Response]
+      def on_ui_failure
+        ::Rack::Response.new do |resp|
+          target = login_url + '?url=' + escape(attempted_path)
+          if env['aker.session_expired']
+            target += '&session_expired=true'
+          end
+          resp.redirect(target)
+        end
+      end
+
+      ##
+      # The path at which the login form will be accessible, as
+      # configured in the specified context.
+      #
+      # This path is specified relative to the application's mount point.  If
+      # you're looking for the absolute URL of the login form, you need to use
+      # {#login_url}.
+      #
+      # @param [Aker::Configuration] configuration the configuration
+      #   from which to derive the login path.
+      #
+      # @return [String]
+      def login_path(configuration)
+        configuration.parameters_for(:rack)[:login_path]
+      end
+      private :login_path
+    end
+  end
+end

data/lib/aker/form.rb

@@ -0,0 +1,26 @@
+require 'aker'
+
+module Aker
+  ##
+  # The Aker mode that supports a traditional HTML login form, and its
+  # support infrastructure.
+  module Form
+    autoload :CustomViewsMode,        'aker/form/custom_views_mode'
+    autoload :LoginFormAssetProvider, 'aker/form/login_form_asset_provider'
+    autoload :Middleware,             'aker/form/middleware'
+    autoload :Mode,                   'aker/form/mode'
+
+    ##
+    # @private
+    class Slice < Aker::Configuration::Slice
+      def initialize
+        super do
+          register_mode Mode
+          register_mode CustomViewsMode
+        end
+      end
+    end
+  end
+end
+
+Aker::Configuration.add_default_slice(Aker::Form::Slice.new)

data/lib/aker/group.rb

@@ -0,0 +1,67 @@
+require 'tree'
+
+require 'aker'
+
+module Aker
+  ##
+  # The authority-independent representation of a group.
+  #
+  # Groups can be related in a tree. If so, a membership in an
+  # ancestor group implies membership in all its descendents.
+  #
+  # @see http://rubytree.rubyforge.org/rdoc/Tree/TreeNode.html
+  class Group < Tree::TreeNode
+    ##
+    # Creates a new group with the given name.  You can add children
+    # using `<<`.
+    #
+    # @param [#to_s] name the desired name
+    # @param [Array,nil] args additional arguments.  Included for
+    #   marshalling compatibility with the base class.
+    def initialize(name, *args)
+      super # overridden to attach docs
+    end
+
+    ##
+    # Determines whether this group or any of its children matches the
+    # given parameter for authorization purposes.
+    #
+    # @param [#to_s,Group] other the thing to compare this
+    #   group to
+    # @return [Boolean] true if the name of this group or any of its
+    #   children is a case-insensitive match for the other.
+    def include?(other)
+      other_name =
+        case other
+        when Group; other.name;
+        else other.to_s;
+        end
+      self.find { |g| g.name.downcase == other_name.downcase }
+    end
+
+    ##
+    # Copy-pasted from parent in order to use appropriate class when
+    # deserializing children.
+    #
+    # @private
+    def marshal_load(dumped_tree_array)
+      nodes = { }
+
+      for node_hash in dumped_tree_array do
+        name        = node_hash[:name]
+        parent_name = node_hash[:parent]
+        content     = Marshal.load(node_hash[:content])
+
+        if parent_name then
+          nodes[name] = current_node = self.class.new(name, content)
+          nodes[parent_name].add current_node
+        else
+          # This is the root node, hence initialize self.
+          initialize(name, content)
+
+          nodes[name] = self    # Add self to the list of nodes
+        end
+      end
+    end
+  end
+end

data/lib/aker/group_membership.rb

@@ -0,0 +1,162 @@
+require 'aker'
+
+module Aker
+  ##
+  # The authority-independent representation of a user's association
+  # with a particular group, possibly constrained by affiliate.
+  class GroupMembership
+    ##
+    # The affiliate IDs to which this membership is scoped.  If this
+    # array is blank or nil, the membership applies to all affiliates.
+    #
+    # An "affiliate" is an arbitrary scope designator for a
+    # membership. The specific form will depend on the authority that
+    # is authorizing the user.
+    #
+    # @return [Array<Object>]
+    attr_accessor :affiliate_ids
+
+    ##
+    # Create a new instance.
+    #
+    # @param [Group] group the group for which this object records
+    #   membership
+    def initialize(group)
+      @group = group
+    end
+
+    ##
+    # Determines whether this membership applies to the given
+    # affiliate.
+    #
+    # @param [Object] affiliate_id
+    # @return [Boolean]
+    def include_affiliate?(affiliate_id)
+      affiliate_ids.blank? ? true : affiliate_ids.include?(affiliate_id)
+    end
+
+    ##
+    # @return [String] the name of the group for which this object
+    #   indicates membership.
+    def group_name
+      self.group.name
+    end
+
+    ##
+    # @return [Group] the group for which this is a membership
+    def group
+      @group
+    end
+
+    def affiliate_ids
+      @affiliate_ids ||= []
+    end
+  end
+
+  ##
+  # An authority-independent collection of all the group memberships
+  # for a particular user at a particular portal.
+  class GroupMemberships < Array
+    ##
+    # The portal for which all these group memberships apply.
+    #
+    # @return [Symbol]
+    attr_reader :portal
+
+    # n.b.: if you add more attributes, be sure to add them to the
+    # custom serialization.
+
+    ##
+    # Create a new instance.
+    #
+    # @param [#to_sym] portal
+    def initialize(portal)
+      @portal = portal.to_sym
+    end
+
+    ##
+    # Determines whether this collection indicates that the user is
+    # authorized in the the given group, possibly constrained by one
+    # or more affiliates.
+    #
+    # (Note that this method hides the superclass `include?` method.)
+    #
+    # @param [Group,#to_s] group the group in question or its name
+    # @param [Array<Object>,nil] *affiliate_ids the affiliates to use to
+    #   constrain the query.
+    #
+    # @return [Boolean] true so long as the user is authorized in
+    #   `group` for **at least one** of the specified affiliates.  If
+    #   no affiliates are specified, only the groups themselves are
+    #   considered.
+    def include?(group, *affiliate_ids)
+      !find(group, *affiliate_ids).empty?
+    end
+
+    ##
+    # Finds the group memberships that match the given group, possibly
+    # constrained by one or more affiliates.
+    #
+    # (Note that this method hides the `Enumerable` method `find`.
+    # You can still use it under its `detect` alias.)
+    #
+    # @param [Group,#to_s] group the group in question or its name
+    # @param [Array<Object>,nil] *affiliate_ids the affiliates to use to
+    #   constrain the query.
+    #
+    # @return [Array<GroupMembership>]
+    def find(group, *affiliate_ids)
+      candidates = self.select { |gm| gm.group.include?(group) }
+      return candidates if affiliate_ids.empty?
+      candidates.select { |gm| affiliate_ids.detect { |id| gm.include_affiliate?(id) } }
+    end
+
+    ##
+    # Custom serialization for this array.  Needed because we need to
+    # serialize the full tree for all referenced groups in order to be
+    # able to do {#include?} and {#find} correctly on the deserialized
+    # result.
+    #
+    # @return [Hash] suitable for passing to {#marshal_load}
+    def marshal_dump
+      {
+        :group_roots => find_group_roots,
+        :memberships => dump_gm_hashes,
+        :portal => portal
+      }
+    end
+
+    ##
+    # Custom deserialization for this array.  Reverses
+    # {#marshal_dump}.
+    #
+    # @return [void]
+    def marshal_load(dump)
+      @portal = dump[:portal]
+      roots = dump[:group_roots]
+      dump[:memberships].each do |gm_hash|
+        self << GroupMembership.new(find_group_from_roots(gm_hash[:group_name], roots)).
+          tap { |gm| gm.affiliate_ids.concat(gm_hash[:affiliate_ids]) }
+      end
+    end
+
+    private
+
+    def find_group_from_roots(group_name, roots)
+      roots.each do |root|
+        root.each do |group|
+          return group if group.name == group_name
+        end
+      end
+      raise "Could not find #{group_name} in any of the roots (#{roots.inspect})"
+    end
+
+    def find_group_roots
+      self.collect { |gm| gm.group.root }.uniq
+    end
+
+    def dump_gm_hashes
+      self.collect { |gm| { :group_name => gm.group_name, :affiliate_ids => gm.affiliate_ids } }
+    end
+  end
+end