padrino-auth 0.0.12

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: fe0f85bb7353604b8ba83cc1f2065702a18249a6
+  data.tar.gz: c6e23562acdc4d84ad7df25f53551fc673bd8bd1
+SHA512:
+  metadata.gz: 7fbe645faf1515806edb29a26d5dad59130fce3a291c666bffdc9585e0aa941e4d324b26fa4be930f2ca4cac1f2c3ba2386138474c8641fe585d07dcae1e2840
+  data.tar.gz: e79a584a29ea547eb66b78afb232add8adb5e8f0560983f5cef18cd3fc2483eeed21488a2df4b370dd5ce52f5643c41713b004c8ce37b999a26f5ae3dd9c122e

data/.gitignore

@@ -0,0 +1,34 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/EXAMPLES.md

@@ -0,0 +1,249 @@
+### Authentication and authorization example
+
+```
+# sketchup some database model
+module Character
+  extend self
+
+  # db model must have authenticate method which should response with credentials object on
+  # the calls of { :email => 'a@b', :password => 'abc' } to authenticate by email and password
+  # or { :id => 42 } to restore credentials from id saved in session or another persistance storage
+  def authenticate(credentials)
+    case
+    when credentials[:email] && credentials[:password]
+      target = all.find{ |resource| resource.id.to_s == credentials[:email] }
+      (target && target.name.gsub(/[^A-Z]/,'') == credentials[:password]) ? target : nil
+    when credentials.has_key?(:id)
+      all.find{ |resource| resource.id == credentials[:id] }
+    else
+      false
+    end
+  end
+
+  # example collection of users
+  def all
+    @all = [
+      OpenStruct.new(:id => :bender,   :name => 'Bender Bending Rodriguez', :role => :robots  ),
+      OpenStruct.new(:id => :leela,    :name => 'Turanga Leela',            :role => :mutants ),
+      OpenStruct.new(:id => :fry,      :name => 'Philip J. Fry',            :role => :humans  ),
+      OpenStruct.new(:id => :ami,      :name => 'Amy Wong',                 :role => :humans  ),
+      OpenStruct.new(:id => :zoidberg, :name => 'Dr. John A. Zoidberg',     :role => :lobsters),
+    ]
+  end
+end
+
+module Example; end
+# define an application class
+class Example::App < Padrino::Application
+  set :login_model, :character
+
+  register Padrino::Rendering
+  register Padrino::Helpers
+  register Padrino::Login
+  register Padrino::Access
+  enable :sessions
+
+  set_access :*, :allow => :index
+  set_access :humans, :allow => :restricted
+
+  get(:index){ 'index' }
+  get(:restricted){ 'secret' }
+end
+```
+
+After rackup we have:
+
+http://localhost:9292/ gets index  
+http://localhost:9292/restricted gets us redirected to '/login'
+
+If we fill the form with 'leela' and her password 'TL' we get logged in and
+redirected to '/restricted' location we tried to visit earlier, but Leela has
+no access to it and we get 403 status.
+
+http://localhost:9292/login now if we visit '/login' again and ented 'ami'
+and his password 'AW' we can get to '/restricted' location.
+
+http://localhost:9292/restricted now gets 'secret' content
+
+### Authorization-only example
+
+```ruby
+# sketchup some database model
+module Character
+  extend self
+
+  # db model must have authenticate method which should response with credentials object on
+  # the calls of { :email => 'a@b', :password => 'abc' } to authenticate by email and password
+  # or { :id => 42 } to restore credentials from id saved in session or another persistance storage
+  def authenticate(credentials)
+    case
+    when credentials[:email] && credentials[:password]
+      target = all.find{ |resource| resource.id.to_s == credentials[:email] }
+      target.name.gsub(/[^A-Z]/,'') == credentials[:password] ? target : nil
+    when credentials.has_key?(:id)
+      all.find{ |resource| resource.id == credentials[:id] }
+    else
+      false
+    end
+  end
+
+  # example collection of users
+  def all
+    @all = [
+      OpenStruct.new(:id => :bender,   :name => 'Bender Bending Rodriguez', :role => :robots  ),
+      OpenStruct.new(:id => :leela,    :name => 'Turanga Leela',            :role => :mutants ),
+      OpenStruct.new(:id => :fry,      :name => 'Philip J. Fry',            :role => :humans  ),
+      OpenStruct.new(:id => :ami,      :name => 'Amy Wong',                 :role => :humans  ),
+      OpenStruct.new(:id => :zoidberg, :name => 'Dr. John A. Zoidberg',     :role => :lobsters),
+    ]
+  end
+end
+
+module Example; end
+# define an application class
+class Example::App < Padrino::Application
+  register Padrino::Access
+
+  # authorization module has no built-in persistance storage, so we have to implement it:
+  enable :sessions
+  helpers do
+    def credentials
+    puts settings.permissions.inspect
+      @visitor ||= Character.authenticate(:id => session[:visitor_id])
+    end
+    def credentials=(user)
+      @visitor = user
+      session[:visitor_id] = @visitor ? @visitor.id : nil
+    end
+  end
+
+  # simple authentication controller
+  get(:login, :with => :id) do
+    # this is an example, do not authenticate by user id in real apps
+    self.credentials = Character.authenticate(:id => params[:id].to_sym)
+  end
+
+  # allow everyone to visit '/login'
+  set_access :*, :allow => :login
+
+  # example action
+  get(:index){ 'foo' }
+
+  # robots are allowed to bend
+  set_access :robots, :allow => :bend
+  get(:bend){ 'bend' }
+
+  # humans and robots are allowed to live on surface
+  controller :surface do
+    set_access :humans, :robots
+    get(:live) { 'live on the surface' }
+  end
+
+  # mutants are allowed to live on surface, humans are allowed to visit
+  controller :sewers do
+    set_access :mutants
+    set_access :humans, :allow => :visit
+    get(:live) { 'live in the sewers' }
+    get(:visit) { 'visit the sewers' }
+  end
+end
+```
+
+That's it, rackup it and see what's up:
+
+http://localhost:9292/ => 403 shows Forbidden  
+http://localhost:9292/login/leela => 200 logs Leela in
+
+Now we can see that Leela is allowed to live in sewers:
+
+http://localhost:9292/sewers/live => 200 live in sewers
+
+Now check if robots can bend and humans to visit sewers:
+
+http://localhost:9292/login/fry  
+http://localhost:9292/sewers/live  
+http://localhost:9292/sewers/visit
+
+http://localhost:9292/login/bender  
+http://localhost:9292/bend  
+http://localhost:9292/stop_partying
+
+### Authentication-only example
+
+```ruby
+# sketchup some database model
+module Character
+  extend self
+
+  # db model must have authenticate method which should response with credentials object on
+  # the calls of { :email => 'a@b', :password => 'abc' } to authenticate by email and password
+  # or { :id => 42 } to restore credentials from id saved in session or another persistance storage
+  def authenticate(credentials)
+    case
+    when credentials[:email] && credentials[:password]
+      target = all.find{ |resource| resource.id.to_s == credentials[:email] }
+      (target && target.name.gsub(/[^A-Z]/,'') == credentials[:password]) ? target : nil
+    when credentials.has_key?(:id)
+      all.find{ |resource| resource.id == credentials[:id] }
+    else
+      false
+    end
+  end
+
+  # example collection of users
+  def all
+    @all = [
+      OpenStruct.new(:id => :bender,   :name => 'Bender Bending Rodriguez', :role => :robots  ),
+      OpenStruct.new(:id => :leela,    :name => 'Turanga Leela',            :role => :mutants ),
+      OpenStruct.new(:id => :fry,      :name => 'Philip J. Fry',            :role => :humans  ),
+      OpenStruct.new(:id => :ami,      :name => 'Amy Wong',                 :role => :humans  ),
+      OpenStruct.new(:id => :zoidberg, :name => 'Dr. John A. Zoidberg',     :role => :lobsters),
+    ]
+  end
+end
+
+module Example; end
+# define an application class
+class Example::App < Padrino::Application
+  set :login_model, :character
+
+  register Padrino::Rendering
+  register Padrino::Helpers
+  register Padrino::Login
+  enable :sessions
+
+  get(:index){ 'index' }
+  get(:restricted){ 'secret' }
+
+  # if we plan to add custom authorization we need to define #authorized? helper
+  helpers do
+    def authorized?
+      restricted = ['/restricted'].include?(request.env['PATH_INFO'])
+      if credentials
+        case 
+        when credentials.id == :bender
+          true
+        else
+          !restricted
+        end
+      else
+        !restricted
+      end
+    end
+  end
+end
+```
+
+After rackup we have:
+
+http://localhost:9292/ gets index  
+http://localhost:9292/restricted gets us redirected to '/login'
+
+If we fill the form with 'leela' and her password 'TL' we get logged in and
+redirected to '/restricted' location we tried to visit earlier, but Leela has
+no access to it and we get 403 status.
+
+http://localhost:9292/login now if we visit '/login' again and ented 'bender'
+and his password 'BBR' we can get to '/restricted' location.
+
+http://localhost:9292/restricted now gets 'secret' content

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Igor Bochkariov
+
+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 the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,118 @@
+## Authorization and authentication modules for Padrino framework
+
+### Overview
+
+This padrino-auth provides the means to authenticate and authorize users.
+These modules are designed to be independent but compatible with each other.
+
+### Padrino::Login, an authentication module for Padrino
+
+Authentication means identifying the user by comparing provided parameters
+(usually login or email and password) with the credentials stored in the
+application database and selecting the matched one. This module provides
+a simple login form and related helpers methods including saving and
+restoring user location.
+
+#### Usage
+
+##### Holding a session
+
+Make sure you have sessions enabled: `enable :sessions`.
+
+If you use a different persistence storage you will have to make #session hash
+available to call in your app. `Padrino::Login` stores credentials `id` in
+session[settings.session_key]. You can customize session_key by calling
+`set :session_key, :current_credentials_id`. Default session_key name is
+`"_login_#{app.app_name}"`.
+
+##### Taming a model
+
+By default `Padrino::Login` uses credentials model name `Account`. You can
+customize it by setting `set :login_model, :user`.
+
+Usually a set of credentials are stored in application database. To access
+stored credentials `Padrino::Login` uses `Account.authenticate` class method.
+The Account model must provide this class method in at least two forms:
+authenticate with email/password, or with id. `Account.authenticate` is called
+
+ * with hash like `{ :email => 'user@example.com', :password => 'mypass' }`
+   to authenticate by email and password in response to user request
+ * with hash `{ :id => 42 }` to restore credentials from session
+
+##### Accessing credentials (optional)
+
+To be able to access current credentials of the signed user your app will
+have to provide application helpers. By default `Padrino::Login` adds simple
+reader and writer with names `credentials` and `credentials=(user)`. You can
+customize helper name by setting `set :credentials_accessor, :visitor` and you
+can override default accessor by defining your own reader and writer helpers
+with the said names.
+
+ * the reader is called before checking if the user is signed in
+ * the writer is called after authenticating user's credentials or restoring
+   it from session
+
+##### Bypassing authentication (optional)
+
+By default this option is disabled. To enable it you can call
+`enable :login_bypass`. 
+
+In development environment it sometimes is convenient to be able to bypass
+authentication. If you do this you also have to extend your model
+`Account.authenticate` class method to be able to return default credentials in
+response to hash `{ :bypass => true }`. This way if the user authenticates with
+parameter `bypass` she will be assigned the credentials returned by you model
+and redirected to the stored location.
+
+##### Customizing the login process (optional)
+
+By default `Padrino::Login` registers a simple login controller for your app
+and binds it to `/login`.
+
+To customize this url it you can call `set :login_url, '/signin'`. Also it's
+possible to disable registering the default controller by calling
+`disable :login_controller`. If you do so you should provide a controller for
+your custom login url which on request of authentication will call
+`#authenticate` helper. If the result is true it should call
+`#restore_location`, else it should show an error. Or you can do whatever you
+like, it's your controller after all.
+
+##### Synergizing with Padrino::Access and other things (info)
+
+`Padrino::Login` tries to inform `Padrino::Access` that `/login` url should be
+accessible for unauthenticated users by setting default
+`set(:login_permissions) { set_access(:*, :allow => :*, :with => :login) }`.
+Yes, it's a Proc and `Padrino::Access` tries to call it when registers itself.
+
+If you name your controller another way you must redefine this. If you use
+another authorization solution you also should configure it to allow visiting
+`/login` url without having to authenticate.
+
+##### Redirecting the user (info)
+
+To authenticate users `Padrino::Login` defines Sinatra `before_filter` which
+checks things and acts accordingly.
+
+The first thing is if the user is already logged in. It uses the credentials
+reader we mentioned before, or tries to restore credentials from session.
+
+The second thing is if the user is authorized to look at the requested page.
+To do so `Padrino::Login` calls `#authorized?` helper and checks it's bollean
+result. If this helper does not exist then your app is considered not requiring
+authorization. If it exists and responds with `true` then `before_filter`
+passes. If the helper exists and returns `false` then the user's location
+is saved and the user herself is redirected to login url.
+
+`#authorized?` helper should be defined in your app if you want access control.
+
+##### Finally registering
+
+Call `register Padrino::Login` and you are ready to roll.
+
+### Padrino::Access, an authorization module for Padrino
+
+https://github.com/padrino/padrino-framework/wiki/Padrino-authorization-module
+
+### Examples
+
+[EXAMPLES.md](EXAMPLES.md)

data/Rakefile

@@ -0,0 +1,12 @@
+RAKE_ROOT = __FILE__
+
+require 'rubygems'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'test'
+  test.test_files = Dir['test/**/test_*.rb']
+  test.verbose = true
+end
+
+task :default => :test