tachiban 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 664c75489c53111c15f0624f918846a6e64c837e
-  data.tar.gz: 82a5a8531f61133be195b32f7c0c431baf0c8d79
+  metadata.gz: 32f1f2b6604c7cda5393b06aad44f4ea84397a0d
+  data.tar.gz: 6e6dbbb843fae38ed80dc10034071da0b669d3ef
 SHA512:
-  metadata.gz: dbb45889b53b0a7745f3cc42c5f41c270741369fcad73c957366859485f59313be4ffd7b2d2dc1064b30a6317a394a444c0b3fd8966979fbe47d3a4aa527df5a
-  data.tar.gz: b605d49a0f8c94f2a8878095ea9a0319d782e1b174706a02f58da294f69e7d3eff393708b55eab09f69c6e3c8de874d77e74053f4b5697ae734fc723a55a3aaf
+  metadata.gz: ee08ab9357babdfef72ad367eb31f2815a1dbfffed18d2c0e526b0d9b411edee1bfc1124d5cd02052677b08cd966a4e114ac55365fa9fd2d30440e72ed0edc7b
+  data.tar.gz: 98e960466e21300d6973b405d493ecba1cb691a58e85296775468390a0c9acebe678cd8ce31665071342c025b5ecf731fbcf1b839f75b9a6283f009a427c2230

data/README.md

@@ -1,6 +1,6 @@
 # Tachiban
 
-[![Join the chat at https://gitter.im/sebastjan-hribar/tachiban](https://badges.gitter.im/sebastjan-hribar/tachiban.svg)](https://gitter.im/sebastjan-hribar/tachiban?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![Join the chat at https://gitter.im/sebastjan-hribar/tachiban](https://badges.gitter.im/sebastjan-hribar/tachiban.svg)](https://gitter.im/sebastjan-hribar/tachiban?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Gem Version](https://badge.fury.io/rb/tachiban.svg)](https://badge.fury.io/rb/tachiban)
 
 Tachiban (立ち番 - standing watch) provides simple authentication system for [Hanami web applications](http://hanamirb.org/) by using bcrypt for password hashing and
 offers the following functionalities (with methods listed below
@@ -9,8 +9,10 @@ offers the following functionalities (with methods listed below
 - Login
 - Authentication
 - Session handling
+- Password reset
+- Authorization
 
-The Tachiban logic and code were extracted from a Hanami based web app using
+The Tachiban logic (apart from the Authorization) and code were extracted from a Hanami based web app using
 Hanami::Model and was also used in a Camping based web app using Active Record.
 
 
@@ -43,16 +45,27 @@ end
 ## Usage
 
 #### Prerequisites
-The entity for which authentication is used must have the
-attribute `hashed_pass` to hold the generated hashed password.
+Prior to logging in or authenticating the user, retrieve the entity from the
+database and assign it to the instance variable of `@user`.
+
+The password reset methods require the user entity to have the following attributes:
+**token** and **password_reset_sent_at (set as `Time.now`)**. The token can be used to compose
+ the password reset url and to later retrieve the correct user from
+the database when the user visits the password reset url.
 
-Prior to authenticating or logging in the user, retrieve them from the database and assign them to the instance variable of `@user`.
+The **password_reset_sent_at** can be used to check the reset link validity.
 
+The only prerequisite for the authorization is the attribute of **role** for the user entity.
 
-#### Usage by features
+
+#### Usage
 
 ###### Signup
-To create a user with a hashed password use the `hashed_password(password)` method for the password and store it as the user's attribute `hashed_pass`.
+The entity for which authentication is used must have the
+attribute `hashed_pass` to hold the generated hashed password.
+
+To create a user with a hashed password use the `hashed_password(password)`
+method for the password and store it as the user's attribute `hashed_pass`.
 
 *Example*
 
@@ -69,13 +82,18 @@ end
 ```
 
 ###### Login
-To authenticate a user use the `authenticated?(input_password)` method and log them in with the `login` method. Authentication is successful if the user exists and passwords match.
+To authenticate a user use the `authenticated?(input_password)` method and log
+them in with the `login` method. Authentication is successful if the user exists and passwords match.
 
-The user is logged in by setting the user object as the `session[:current_user]`. After the user is logged in the session start time is defined as `session[:session_start_time] = Time.now`. A flash message is also assigned as `flash[:success_notice] = flash_message`.
+The user is logged in by setting the user object as the `session[:current_user]`.
+After the user is logged in the session start time is defined as
+`session[:session_start_time] = Time.now`. A flash message is also
+assigned as `flash[:success_notice] = flash_message`.
 
-The `session[:session_start_time]` is then used by the `session_expired?` method to determine whether the session has expired or not.
+The `session[:session_start_time]` is then used by the `session_expired?`
+method to determine whether the session has expired or not.
 
-*Example*
+*Example of session creation for an entity*
 
 ```ruby
 # Create action for an entity session
@@ -88,8 +106,8 @@ login("You have been successfully logged in.") if authenticated?(password)
 
 
 ###### Authentication
-To check whether the user is logged in use the `check_for_logged_in_user
-` method.
+To check whether the user is logged in use the `check_for_logged_in_user` method.
+If the user is not logged in the `logout` method takes over.
 
 
 ###### Session handling
@@ -138,15 +156,74 @@ module Web
 end
 ```
 
+
+###### Password reset
+The password reset feature provides a few simple methods to generate a
+token, email subject and body. It is also possible to specify and
+check the validity of the password reset url.
+
+```ruby
+token # => "YbRucc8YUlFJrYYp04eQKQ"
+```
+
+```ruby
+email_subject(SomeApp) # => "SomeApp -- password reset request"
+```
+
+
+Provide the base url, the token and the number and type of the time units
+ for the validity of the link.
+
+```ruby
+body = email_body(base_url, url_token, 2, "hour")
+# => "Visit this url to reset your password: http://localhost:2300/passwordupdate/asdasdasdaerwrw.
+#     The url will be valid for 2 hour(s).")
+```
+
+The link validity must me specified in seconds. The method compares the
+current time with the time when the password reset link was sent increased
+by the link validity: `Time.now > @user.password_reset_sent_at + link_validity`
+
+```ruby
+password_reset_url_valid?(link_validity)
+```
+
+
+###### Authorization
+Authorization support was setup as inspired by [this blog post](http://billpatrianakos.me/blog/2013/10/22/authorize-users-based-on-roles-and-permissions-without-a-gem/).
+
+Authorization features support the generation of policy files for each controller where authorized roles are specified for each action.
+
+```ruby
+tachiban -n mightyPoster -p post
+```
+The above CLI command will generate a policy file for the application mightyPoster (not the project) and the controller post. The file will be generated as `myProject/lib/mightyPoster/policies/PostPolicy.rb`
+
+Each application would have its own `app/policies` folders.
+
+**The command must be run in the project root folder.**
+
+Once the file is generated the authorized roles variables in the initialize block for required actions need to be uncommneted and supplied with specific roles.
+
+Then we can check if a user is authorized:
+
+```ruby
+authorized?(controller, role, action)
+```
+
+
 ### ToDo
-1. Add support for password reset and update.
-2. Add support for level based authorizations.
 
-<!-- ## Development
+- Add support for level based authorizations. [x]
+- Add generators for adding authorization rules to existing policies.
+- Add generators for entities with required attributes.
+
+
+## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org). -->
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 

data/bin/tachiban

@@ -0,0 +1,2 @@
+#!/usr/bin/env ruby
+require_relative "../lib/tachiban/commands/commands.rb"

data/lib/tachiban.rb

@@ -116,6 +116,40 @@ private
       end
     end
 
+
+  # ### Password reset ###
+
+    def token
+      SecureRandom.urlsafe_base64
+    end
+
+    def email_subject(app_name)
+      "#{app_name} -- password reset request"
+    end
+
+    def email_body(url, token, link_validity, time_unit)
+      "Visit this url to reset your password: #{url}#{token}. \n
+      The url will be valid for #{link_validity} #{time_unit}(s)."
+    end
+
+    # State the link_validity in seconds.
+    def password_reset_url_valid?(link_validity)
+      Time.now > @user.password_reset_sent_at + link_validity
+    end
+
+
+  # ### Authorization ###
+  # The authorized? method checks if the specified user has the required role
+  # and permission to access the action. It returns true or false and
+  # provides the basis for further actions in either case.
+  #
+  # Example: redirect_to "/" unless authorized?
+
+    def authorized?(controller, role, action)
+      Object.const_get(controller.downcase.capitalize + "Policy").new(role).send("#{action.downcase}?")
+    end
+
+
   end
 end
 

data/lib/tachiban/commands/commands.rb

@@ -0,0 +1,45 @@
+#!/usr/bin/env ruby
+require 'optparse'
+require_relative "../policy_generator/policy_generator.rb"
+
+
+options = {}
+optparse = OptionParser.new do |opts|
+  opts.banner = "\nHanami authorization policy generator
+Usage: tachiban -n myapp -p user
+Flags:
+\n"
+
+  opts.on("-n", "--app_name APP", "Specify the application name for the policy") do |app_name|
+    options[:app_name] = app_name
+  end
+
+  opts.on("-p", "--policy POLICY", "Specify the policy name") do |policy|
+    options[:policy] = policy
+  end
+
+  opts.on("-h", "--help", "Displays help") do
+    puts opts
+    exit
+  end
+
+end
+
+
+begin
+  optparse.parse!
+  puts "Add flag -h or --help to see usage instructions." if options.empty?
+  mandatory = [:app_name, :policy]
+  missing = mandatory.select{ |arg| options[arg].nil? }
+  unless missing.empty?
+    raise OptionParser::MissingArgument.new(missing.join(', '))
+  end
+
+rescue OptionParser::InvalidOption, OptionParser::MissingArgument
+  puts $!.to_s
+  puts optparse
+  exit
+end
+
+puts "Performing task with options: #{options.inspect}"
+generate_policy("#{options[:app_name]}", "#{options[:policy]}") if options[:policy]

data/lib/tachiban/policy_generator/policy_generator.rb

@@ -0,0 +1,58 @@
+require 'fileutils'
+
+# The generate_policy method creates the policy file for specified
+# application and controller. By default all actions to check against
+# are commented out.
+# Uncomment the needed actions and define appropriate user role.
+
+def generate_policy(app_name, controller_name)
+  app_name = app_name
+  controller = controller_name.downcase.capitalize
+  policy_txt = <<-TXT
+    class #{controller}Policy
+      def initialize(role)
+        @user_role = role
+
+        # Uncomment the required roles and add the
+        # appropriate user role to the @authorized_roles* array.
+
+        # @authorized_roles_for_new = []
+        # @authorized_roles_for_create = []
+        # @authorized_roles_for_show = []
+        # @authorized_roles_for_index = []
+        # @authorized_roles_for_edit = []
+        # @authorized_roles_for_update = []
+        # @authorized_roles_for_destroy = []
+      end
+
+      def new?
+        @authorized_roles_for_new.include? @user_role
+      end
+      def create?
+        @authorized_roles_for_create.include? @user_role
+      end
+      def show?
+        @authorized_roles_for_show.include? @user_role
+      end
+      def index?
+        @authorized_roles_for_index.include? @user_role
+      end
+      def edit?
+        @authorized_roles_for_edit.include? @user_role
+      end
+      def update?
+        @authorized_roles_for_update.include? @user_role
+      end
+      def destroy?
+        @authorized_roles_for_destroy.include? @user_role
+      end
+    end
+    TXT
+
+
+  FileUtils.mkdir_p "lib/#{app_name}/policies" unless File.directory?("lib/#{app_name}/policies")
+  unless File.file?("lib/#{app_name}/policies/#{controller}Policy.rb")
+    File.open("lib/#{app_name}/policies/#{controller}Policy.rb", 'w') { |file| file.write(policy_txt) }
+  end
+  puts("Generated policy: lib/#{app_name}/policies/#{controller}Policy.rb") if File.file?("lib/#{app_name}/policies/#{controller}Policy.rb")
+end

data/lib/tachiban/version.rb

@@ -1,3 +1,3 @@
 module Tachiban
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

data/tachiban.gemspec

@@ -14,8 +14,7 @@ Gem::Specification.new do |spec|
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency "bundler", "~> 1.11"
@@ -24,10 +23,10 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "hanami-model", "~> 1.0"
   spec.add_development_dependency "timecop", "0.8.1"
   spec.add_development_dependency 'hanami-controller', "~> 1.0"
-  spec.add_development_dependency 'hanami-router'
+  spec.add_development_dependency 'hanami-router', "~> 1.0"
   spec.add_development_dependency 'pry'
 
   spec.add_runtime_dependency "bcrypt", "~> 3.1"
   spec.add_runtime_dependency 'hanami-controller', "~> 1.0"
-  spec.add_runtime_dependency 'hanami-router'
+  spec.add_runtime_dependency 'hanami-router', "~> 1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tachiban
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Sebastjan Hribar
 autorequire: 
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2017-04-26 00:00:00.000000000 Z
+date: 2017-08-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -98,16 +98,16 @@ dependencies:
   name: hanami-router
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -154,20 +154,23 @@ dependencies:
   name: hanami-router
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.0'
 description: 
 email:
 - sebastjan.hribar@gmail.com
-executables: []
+executables:
+- console
+- setup
+- tachiban
 extensions: []
 extra_rdoc_files: []
 files:
@@ -180,7 +183,10 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- bin/tachiban
 - lib/tachiban.rb
+- lib/tachiban/commands/commands.rb
+- lib/tachiban/policy_generator/policy_generator.rb
 - lib/tachiban/version.rb
 - tachiban.gemspec
 homepage: https://github.com/sebastjan-hribar/tachiban