authlane 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e1d5209e59fc6178372d91056feaa7f88db1c320
-  data.tar.gz: 03b19e3f8ccffee0f4d3452f4eb4a398f94c9913
+  metadata.gz: 60d5057e5de15303320296fc4968ee7e2e4599b1
+  data.tar.gz: 37bcce0af17f5e6061c380d622de64648f4fce9a
 SHA512:
-  metadata.gz: 62780ea9f8bf9756688a915d84718f2da5326c042467e3fa4cca395b77e6d6fad7ec6cb132237b1e6a23240e19cd5e6f9284924eaee22fff75c94cb63a5719bd
-  data.tar.gz: 52c700e8b936048bdd8c8c2d992b20527226dc52301e1579be95b1a34b025496d2f59d23ce1f698a7e08f47f99464debdcd68b511c98d2cf731df5f174d1494a
+  metadata.gz: f7e5575bfdf4a157890f5653c1ef53b8d3d5843ff068fe7ed48d6863da4613e6208102ebc22d958062b5c8019cb842a35614f45b53bc971a7e488699032e59e2
+  data.tar.gz: e5bc08034ee0ffe129238e1d04c3df7c13ef0cb0688b0b644536385d75e558baf9bac0314172bff973c2208c4cef17e95e5f790882e28d4df53e747a50ab0e5f

data/README.md

@@ -4,11 +4,24 @@ The **AuthLane** Sinatra Extension allows easy User authentication with support
 
 The actual authentication logic (*strategy*) is defined by the Application using a namespaced DSL provided by this extension, while the general Extension configuration is handled with Sinatra's `set` method, which will be described in more detail below.
 
-## Setting up *Sinatra*
+## Installation
 
-**AuthLane** utilizes the standard Sinatra Extension format for *classic*-style applications:
+Get the Gem:
 
 ```
+gem install authlane
+```
+
+Or let Bundler do the work:
+
+``` ruby
+# Gemfile
+gem 'authlane'
+```
+
+**AuthLane** utilizes the standard Sinatra Extension format for *classic*-style applications:
+
+``` ruby
 require 'sinatra'
 require 'sinatra/authlane'
 
@@ -21,7 +34,7 @@ end
 
 As well as `modular`-style applications:
 
-```
+``` ruby
 require 'sinatra/base'
 require 'sinatra/cookies'
 require 'sinatra/authlane'
@@ -33,28 +46,22 @@ class App < Sinatra::Base
   get '/user' do
     protect!
 
-    # Application stuff for signed in users ....
+    # Application stuff for signed in users
   end
 end
- ```
-
-Both setups however require a separate **Session** *Rack middleware*, like `Rack::Session::Cookies`, which you need to provide for your *Sinatra* application (refer to [Sinatra's documentation](http://www.sinatrarb.com/intro.html#Using%20Sessions) on using Sessions).
-
-> **Note:** The inclusion of `sinatra/cookies` helper methods is a requirement by *AuthLane*, which currently it - at least when used modular - does not do automatically.
-
-## Configuring *AuthLane*
+```
 
-### General configuration values
+## Configuration
 
 **AuthLane**'s configuration data is available under Sinatra's `settings` object with the key `:authlane` as a Hash, so changing config values is simply done with Sinatra's `set` method.
 
-```
+``` ruby
 set :authlane, :failed_route => '/login'
 ```
 
 The following settings can be customize (the used values are their defaults):
 
-```
+``` ruby
 set :authlane, :failed_route    => '/user/unauthorized',
                :session_key     => :authlane,
                :remember_cookie => :authlane_token,
@@ -75,4 +82,24 @@ Customize the Cookie's name that stores the token hash used for the *Remember Me
 
 #### `:serialize_user`
 
-The `:serialized_user` settings contains an Array of Symbols telling AuthLane which attributes of the User model that is used to identify Application users should be serialized into `SerializedUser`. It is recommended to not store the whole User object, but note that the *id* (or however the unique identifier of the object is named) attribute is required.
+The `:serialized_user` settings contains an Array of Symbols telling AuthLane which attributes of the User model that is used to identify Application users should be serialized into a `SerializedUser` object. It is recommended to not store the whole User object, but note that the *id* (or however the unique identifier of the object is named) attribute is required.
+
+Alternatively, you can specify your own Class to be used.
+
+``` ruby
+set :authlane, :serialize_user => CustomUser
+```
+
+The `CustomUser`'s `initialize` method receives one argument, which is the User object. What that object is exactly depends on your **Auth strategy** implementation. Basically, it's the User data coming from your application's persisting backend, like a database.
+
+``` ruby
+class CustomUser
+  attr_reader :id
+
+  def initialize(user)
+    @id = user.id
+  end
+end
+```
+
+It is possible to have attribute accessors in your custom Class, but beware that **AuthLane** will *not* save changes back to your backend.

data/lib/authlane/helper.rb

@@ -8,7 +8,8 @@ module Sinatra
     #
     module Helpers
       ##
-      # @note This method uses {#authorized?} to decide, whether to redirect users to `failed_route`.
+      # @note This method uses {#authorized?} to decide, whether to redirect users to your app's `failed_route`.
+      #
       # Check if a user is authorized to view a route.
       #
       # It utilizes the *Role* and *Remember Strategy* to see if a user can access the route this
@@ -33,17 +34,16 @@ module Sinatra
       #     mustache :admin
       #   end
       #
-      # @param [Array] roles A list of role/privilege requirements for a route, set to `nil` to ignore user roles
-      # @param [String] failed_route Custom route to redirect to in case the user is not authorized
+      # @param [Hash] roles A Hash specifying the **Role Strategy** to be used with its key and optional arguments as the value.
+      #               **Example:** `protect! :rolename => arguments`
+      #
+      # @return [void]
       #
       # @see Sinatra::AuthLane.create_role_strategy create_role_strategy
       # @see Sinatra::AuthLane.create_remember_strategy create_remember_strategy
       #
-      def protect!(roles: nil, failed_route: nil)
-        # check for custom :failed_route option
-        failed_route ||= settings.authlane[:failed_route]
-
-        redirect failed_route unless authorized?(roles: roles)
+      def protect!(*roles)
+        redirect settings.authlane[:failed_route] unless authorized?(*roles)
       end
 
       alias_method :protected, :protect!
@@ -64,22 +64,23 @@ module Sinatra
       #     end
       #   end
       #
-      # @param [Array] roles A list of role/privilege requirements for a route, set to `nil` to ignore user roles
+      # @param [Hash] roles A Hash specifying the **Role Strategy** to be used with its key and optional arguments as the value.
+      #               **Example:** `protect! :rolename => arguments`
       #
       # @return [Boolean] `true` if the user is authorized to view a route, `false` otherwise.
       #
       # @see Sinatra::AuthLane::Helpers#protect! protect!
       #
-      def authorized?(roles: nil)
+      def authorized?(*roles)
         # So, if session[settings.authlane[:session_key]] is available
         # we're home, otherwise, see if the 'Remember Me' strategy
         # can come up with some User credentials.
         if session[settings.authlane[:session_key]].nil?
           remember_token = cookies[settings.authlane[:remember_cookie]]
-          remember_strat = self.instance_exec(remember_token, &settings.authlane[:remember_strategy])
+          remember_strat = (remember_token.nil?) ? false : self.instance_exec(remember_token, &settings.authlane[:remember_strategy])
 
           if remember_strat
-            user = Sinatra::AuthLane::SerializedUser.new(remember_strat, settings.authlane[:serialize_user])
+            user = serialize_user(remember_strat)
 
             # The strategy doesn't log in a User,
             # it just comes up with the credentials to do that.
@@ -95,11 +96,19 @@ module Sinatra
           return false
         else
           # User is logged in ...
-          unless roles.nil?
+          if roles.size == 1
             # ... but hold up, he might not have the necessary
             # privileges to access this particular route.
             # Let's ask the 'Role' strategy.
-            strat = self.instance_exec roles, &settings.authlane[:role_strategy]
+            if roles.first.is_a? Hash
+              role_name = roles.first.keys.first
+              role_args = roles.first[role_name]
+            else
+              role_name = roles.first
+              role_args = nil
+            end
+
+            strat = self.instance_exec role_args, &settings.authlane[:role_strategy][role_name]
             return false unless strat
           end
         end
@@ -139,7 +148,7 @@ module Sinatra
           redirect settings.authlane[:failed_route], 303
         end
 
-        session[settings.authlane[:session_key]] = Sinatra::AuthLane::SerializedUser.new(strat, settings.authlane[:serialize_user])
+        session[settings.authlane[:session_key]] = serialize_user(strat)
       end
 
       ##
@@ -182,11 +191,24 @@ module Sinatra
       #     mustache :account
       #   end
       #
-      # @return [SerializedUser] the user data serialized into the Session.
+      # @return [SerializedUser, Object] the user data serialized into the Session, either as `SerializedUser`
+      #   or a custom class set by the developer.
       #
       def current_user
         session[settings.authlane[:session_key]]
       end
+
+      private
+
+      ##
+      #
+      def serialize_user(obj)
+        if settings.authlane[:serialize_user].is_a? Array
+          Sinatra::AuthLane::SerializedUser.new(obj, settings.authlane[:serialize_user])
+        elsif settings.authlane[:serialize_user].is_a? Class
+          settings.authlane[:serialize_user].new(obj)
+        end
+      end
     end
   end
 end

data/lib/authlane/serializeduser.rb

@@ -45,6 +45,14 @@ module Sinatra
         (@user.is_a? Hash) ? @user[a] : @user.__send__(a.to_sym)
       end
 
+      ##
+      #
+      #
+      def []=(key, value)
+        return if key.to_s == 'id'
+        (@user.is_a? Hash) ? @user[key] = value : @user.__send__(key.to_sym, value)
+      end
+
       ##
       # Enables Object-like access to the
       # stored attributes.
@@ -58,9 +66,13 @@ module Sinatra
       #
       def method_missing(m, *args, &block)
         if @user.is_a? Hash
-          @user[m]
+          if m.to_s.index('=').nil?
+            @user[m]
+          elsif m.to_s.index('id').nil?
+            @user[m] = args[1]
+          end
         else
-          @user.__send__(m.to_sym, args)
+          @user.__send__(m, args)
         end
       end
 

data/lib/authlane/version.rb

@@ -2,5 +2,5 @@
 module Authlane
   ##
   # Current AuthLane version number.
-  VERSION = '1.2.0'
+  VERSION = '1.3.0'
 end

data/lib/sinatra/authlane.rb

@@ -86,10 +86,11 @@ module Sinatra
         :session_key       => :authlane,              # name of the Session key to store the login data
         :remember_cookie   => :'authlane.token',      # Cookie name to store 'Remember Me' token
         :auth_strategy     => Proc.new { false },     # strategy to be executed to log in users
-        :role_strategy     => Proc.new { true },      # strategy to be executed to check permissions and roles
+        :role_strategy     => { roles: Proc.new { true } },      # strategy to be executed to check permissions and roles
         :remember_strategy => Proc.new { false },     # strategy to be executed to log in users via 'Remember Me' token
         :forget_strategy   => Proc.new { false },     # strategy to be executed when logging out and 'forgetting' the user
         :serialize_user    => [:id]                   # specify User model fields to be serialized into the login session
+                                                      # or define a custom class which receives the whole User model to handle by itself
     end
 
     class << self
@@ -100,14 +101,12 @@ module Sinatra
       # to be used by passing the implementation as a Code block. It is then
       # stored as a `Proc` object and will be called by AuthLane when needed.
       #
-      # The following describes the `Proc` objects API requirements. It is
-      # required by the implemented strategy to follow these to be usable by AuthLane.
+      # To see the code block's objects API requirements, refer to the {https://github.com/zidizei/authlane/wiki Wiki}.
       #
       # @note While the **Auth** Strategy is primarily responsible for logging in users,
       #   it usually needs to implement some *Remember Me* logic as well.
       #
-      # @return [False, Object] The strategy needs to return the User Model object of
-      #   the user that successfully logged in or - in case of failure - `false`.
+      # @return [Proc] the `Proc` object of the strategy.
       #
       # @example
       #   Sinatra::AuthLane.create_auth_strategy do
@@ -121,7 +120,10 @@ module Sinatra
       # @api AuthLane
       #
       def create_auth_strategy
-        @app.set :authlane, :auth_strategy => Proc.new
+        strat = Proc.new
+
+        @app.set :authlane, :auth_strategy => strat
+        strat
       end
 
       ##
@@ -131,8 +133,7 @@ module Sinatra
       # to be used by passing the implementation as a Code block. It is then
       # stored as a `Proc` object and will be called by AuthLane when needed.
       #
-      # The following describes the `Proc` objects API requirements. It is
-      # required by the implemented strategy to follow these to be usable by AuthLane.
+      # To see the code block's API requirements, refer to the {https://github.com/zidizei/authlane/wiki Wiki}.
       #
       # @example
       #   Sinatra::AuthLane.create_role_strategy do |roles|
@@ -141,18 +142,19 @@ module Sinatra
       #     roles.include? user.role    # See if the list of role names in `roles` contains the user's role
       #   end
       #
-      # @param [Array] roles The `Proc` receives a list of role names (e.g. as Symbols) a User needs to fullfill
-      #   to be allowed to see the route. The list is passed by the {Sinatra::AuthLane::Helpers#authorized? authorized?}
-      #   helper.
+      # @param [Symbol] name The name of the role strategy.
       #
-      # @return [Boolean] The strategy returns `true`, if the user met the necessary role requirements or `false` otherwise.
+      # @return [Proc] the `Proc` object of the strategy.
       #
       # @see Sinatra::AuthLane::Helpers#authorized? authorized?
       #
       # @api AuthLane
       #
-      def create_role_strategy
-        @app.set :authlane, :role_strategy => Proc.new
+      def create_role_strategy(name = :roles)
+        strat = Proc.new
+
+        @app.settings.authlane[:role_strategy][name] = strat
+        strat
       end
 
       ##
@@ -162,8 +164,7 @@ module Sinatra
       # to be used by passing the implementation as a Code block. It is then
       # stored as a `Proc` object and will be called by AuthLane when needed.
       #
-      # The following describes the `Proc` objects API requirements. It is
-      # required by the implemented strategy to follow these to be usable by AuthLane.
+      # To see the code block's API requirements, refer to the {https://github.com/zidizei/authlane/wiki Wiki}.
       #
       # @note The **Remember** Strategy is only responsible for automatically logging in a user.
       #   The necessary Cookie token (plus any additional logic) is usually set in the **Auth** Strategy.
@@ -175,15 +176,17 @@ module Sinatra
       #     (remembered_user.nil?) ? false : remembered_user
       #   end
       #
-      # @return [False, Object] The strategy needs to return the User Model object of
-      #   the user that successfully logged in or - in case of failure - `false`.
+      # @return [Proc] the `Proc` object of the strategy.
       #
       # @see Sinatra::AuthLane::Helpers#authorized? authorized?
       #
       # @api AuthLane
       #
       def create_remember_strategy
-        @app.set :authlane, :remember_strategy => Proc.new
+        strat = Proc.new
+
+        @app.set :authlane, :remember_strategy => strat
+        strat
       end
 
       ##
@@ -193,13 +196,12 @@ module Sinatra
       # to be used by passing the implementation as a Code block. It is then
       # stored as a `Proc` object and will be called by AuthLane when needed.
       #
-      # The following describes the `Proc` objects API requirements. It is
-      # required by the implemented strategy to follow these to be usable by AuthLane.
+      # To see the code block's API requirements, refer to the {https://github.com/zidizei/authlane/wiki Wiki}.
       #
       # @note The **Forget** Strategy is the counter-part to the **Remember** Strategy.
       #   It's responsible for disabling the auto login technique and is called when logging out.
       #
-      # @note While the *Auth* and *Remember Strategy* needs to interact with the Cookie token directly,
+      # @note While the *Auth Strategy* needs to interact with the Cookie token directly,
       #   the *Forget Strategy* does not need to implement the deletion of the Cookie.
       #   This is done automatically by AuthLane behind the scenes.
       #
@@ -209,16 +211,17 @@ module Sinatra
       #     user.token = nil if user.token == token
       #   end
       #
-      # @param [Object] token The `Proc` object receives the *Remember Me* token of the current user.
-      #
       # @see Sinatra::AuthLane::Helpers#unauthorize! unauthorize!
       #
-      # @return [void]
+      # @return [Proc] the `Proc` object of the strategy.
       #
       # @api AuthLane
       #
       def create_forget_strategy
-        @app.set :authlane, :forget_strategy => Proc.new
+        strat = Proc.new
+
+        @app.set :authlane, :forget_strategy => strat
+        strat
       end
     end
   end

data/spec/authlane_helper_spec.rb

@@ -10,9 +10,19 @@ describe Sinatra::AuthLane::Helpers do
 
       use Rack::Session::Cookie, :secret => 'rspec'
 
+      set :authlane, :serialize_user => [:id, :rank]
+
       Sinatra::AuthLane.create_auth_strategy do
         cookies[:'authlane.token'] = 'rspec'
-        { id: '1' }
+        { id: '1', rank: 1 }
+      end
+
+      Sinatra::AuthLane.create_role_strategy do |ranks|
+        current_user[:rank] == ((ranks.nil?) ? 1 : ranks)
+      end
+
+      Sinatra::AuthLane.create_role_strategy(:roles2) do |ranks|
+        current_user[:rank] == ((ranks.nil?) ? 2 : ranks)
       end
 
       get '/protected' do
@@ -32,6 +42,22 @@ describe Sinatra::AuthLane::Helpers do
         protect!
       end
 
+      get '/role1' do
+        protect! :roles
+      end
+
+      get '/role1a' do
+        protect! :roles => 2
+      end
+
+      get '/role2' do
+        protect! :roles2
+      end
+
+      get '/role2a' do
+        protect! :roles2 => 1
+      end
+
       get '/unauthorize' do
         unauthorize!
         protect!
@@ -106,4 +132,28 @@ describe Sinatra::AuthLane::Helpers do
     get '/user'#, {}, { 'rack.session' => { authlane: '1' } }
     expect(last_response.body).to eq('1')
   end
+
+  it "should be able to use role strategy" do
+    get '/authorize'
+    get '/role1'
+    last_response.should be_ok
+  end
+
+  it "should be able to use role strategy with arguments" do
+    get '/authorize'
+    get '/role1a'
+    expect(last_response.headers['location']).to eq('http://example.org/user/unauthorized')
+  end
+
+  it "should be able to use named role strategy" do
+    get '/authorize'
+    get '/role2'
+    expect(last_response.headers['location']).to eq('http://example.org/user/unauthorized')
+  end
+
+  it "should be able to use named role strategy with arguments" do
+    get '/authorize'
+    get '/role2a'
+    last_response.should be_ok
+  end
 end

data/spec/authlane_serializeduser_spec.rb

@@ -53,4 +53,27 @@ describe Sinatra::AuthLane::SerializedUser do
     user[:id].should eql(1)
     user[:name].should be(nil)
   end
+
+  it 'can change specific attributes after initialization from an Object' do
+    user = Sinatra::AuthLane::SerializedUser.new(MockUser.new, [:id])
+    user[:id].should eql(1)
+    user[:name].should be(nil)
+    user[:name] = 'Rspec'
+    user[:name].should eql('Rspec')
+  end
+
+  it 'can change specific attributes after initialization from a Hash' do
+    user = Sinatra::AuthLane::SerializedUser.new({ id: 1, name: nil }, [:id])
+    user[:id].should eql(1)
+    user[:name].should be(nil)
+    user[:name] = 'Rspec'
+    user[:name].should eql('Rspec')
+  end
+
+  it 'can not change id attribute after initialization' do
+    user = Sinatra::AuthLane::SerializedUser.new(MockUser.new, [:id])
+    user[:id].should eql(1)
+    user[:id] = 2
+    user[:id].should eql(1)
+  end
 end

data/spec/sinatra_authlane_spec.rb

@@ -1,16 +1,41 @@
 require File.expand_path '../spec_helper.rb', __FILE__
 
 describe Sinatra::AuthLane do
-  def strategy(type, &block)
+  def create_auth_strategy(&block)
     mock_app do
       register Sinatra::AuthLane
 
-      Sinatra::AuthLane.send "create_#{type}_strategy", &block
+      Sinatra::AuthLane.create_auth_strategy &block
     end
   end
 
+  def create_role_strategy(name = :roles, &block)
+    mock_app do
+      register Sinatra::AuthLane
+
+      Sinatra::AuthLane.create_role_strategy(name, &block)
+    end
+  end
+
+  def create_remember_strategy(&block)
+    mock_app do
+      register Sinatra::AuthLane
+
+      Sinatra::AuthLane.create_remember_strategy &block
+    end
+  end
+
+  def create_forget_strategy(&block)
+    mock_app do
+      register Sinatra::AuthLane
+
+      Sinatra::AuthLane.create_forget_strategy &block
+    end
+  end
+
+
   it "should allow definition of auth strategy" do
-    strategy(:auth) do
+    create_auth_strategy do
       'rspec'
     end
 
@@ -18,15 +43,23 @@ describe Sinatra::AuthLane do
   end
 
   it "should allow definition of role strategy" do
-    strategy(:role) do
+    create_role_strategy do
       'rspec'
     end
 
-    settings.authlane[:role_strategy].yield.should == 'rspec'
+    settings.authlane[:role_strategy][:roles].yield.should == 'rspec'
+  end
+
+  it "should allow definition of named role strategies" do
+    create_role_strategy(:rspec1) do
+      'rspec1'
+    end
+
+    settings.authlane[:role_strategy][:rspec1].yield.should == 'rspec1'
   end
 
   it "should allow definition of remember strategy" do
-    strategy(:remember) do
+    create_remember_strategy do
       'rspec'
     end
 
@@ -34,7 +67,7 @@ describe Sinatra::AuthLane do
   end
 
   it "should allow definition of forget strategy" do
-    strategy(:forget) do
+    create_forget_strategy do
       'rspec'
     end
 

data/spec/sinatra_custom_serializeduser_spec.rb

@@ -0,0 +1,52 @@
+require File.expand_path '../spec_helper.rb', __FILE__
+
+describe Sinatra::AuthLane do
+  class Serialized
+    attr_reader :id
+
+    def initialize(user)
+      serialize(user)
+    end
+
+    def serialize(user)
+      @id = user[:id]
+    end
+  end
+
+  before :all do
+    build_rack_test_session 'rspec'
+
+    mock_app do
+      helpers Sinatra::Cookies
+      register Sinatra::AuthLane
+
+      use Rack::Session::Cookie, :secret => 'rspec'
+
+      set :authlane, serialize_user: Serialized
+
+      Sinatra::AuthLane.create_auth_strategy do
+        cookies[:'authlane.token'] = 'rspec'
+        { id: '1', name: 'rspec' }
+      end
+
+      get '/authorize' do
+        authorize!
+        protect!
+      end
+    end
+  end
+
+  before :each do
+    clear_cookies
+  end
+
+  def current_user
+    Marshal.load(rack_mock_session.cookie_jar['rack.session'].unpack('m*').first)
+  end
+
+  it 'uses custom SerializedUser class instead of the built-in one when specified' do
+    get '/authorize'
+    last_response.should be_ok
+    expect(current_user['authlane']).to be_a Serialized
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: authlane
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Patrick Lam
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-12 00:00:00.000000000 Z
+date: 2015-04-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sinatra
@@ -117,6 +117,7 @@ files:
 - spec/authlane_helper_spec.rb
 - spec/authlane_serializeduser_spec.rb
 - spec/sinatra_authlane_spec.rb
+- spec/sinatra_custom_serializeduser_spec.rb
 - spec/spec_helper.rb
 homepage: 
 licenses:
@@ -138,7 +139,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5
+rubygems_version: 2.4.1
 signing_key: 
 specification_version: 4
 summary: Simple User authentication and roles for Sinatra.
@@ -146,5 +147,6 @@ test_files:
 - spec/authlane_helper_spec.rb
 - spec/authlane_serializeduser_spec.rb
 - spec/sinatra_authlane_spec.rb
+- spec/sinatra_custom_serializeduser_spec.rb
 - spec/spec_helper.rb
 has_rdoc: