knock_once 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3e1ee1a4bfcaa9e4488162846e441581bb26c26e
-  data.tar.gz: 21858d81ee43780b5df9cdd4edeed77596e02d20
+  metadata.gz: a6b19f4ce7b6ecf6860cb9aee3b2af98081f49ee
+  data.tar.gz: e1a5b63432a06499ed5c0d80dfc7b675d6ec9b76
 SHA512:
-  metadata.gz: ab78c146dc10fdfff5bf338bf56a34dbcb78b26a8106e91228ca5d5ce5ad8d2bc70764e45367ecc5124acb58dadc6932e8a454f1e82b3f504eb3f3936b4d0f62
-  data.tar.gz: 5e26f6aafe38cb4b0e9cd66fe965ecdc6225f2878c6aa571f2507cddd165a1f64ab364de5f887c2a0979da7aed533a57a5eb98c6ec750ffdf3712f0329aaeb9f
+  metadata.gz: 94cb28e74d99f01fd89f8c141ce9d5eb9849b109eb8505b5a6bf8e0563fb5256e910074630629edb7cdce978e4deddb52c48af1595fdc8ab8d357ae69a98943a
+  data.tar.gz: c03af0c55fe402d1c127eeeafaa1dff2209b0cb5a5f371357810b6ee9783e6d4a729df3290c81a5adbf5a9c8fd2c1d6a8088f0795fa8d347e9d49b253696ba8b

data/README.md

@@ -1,6 +1,6 @@
 # KnockOnce
-knock_once is a user auth gem built on top of [knock](https://github.com/nsarno/knock). The goals of knock_once are twofold:
-* Provide the minimum functionality required to register, authenticate, and reset user passwords. In this sense, minimum means only basic functionality which should apply to the largest number of users.
+knock_once is a user auth gem built on top of [knock](https://github.com/nsarno/knock) to provide a basic JWT user auth system for APIs. The goals of knock_once are twofold:
+* Provide the minimum functionality required to register, authenticate, and reset user passwords. 
 * Provide easy extensibility and customization. Because the first goal is to provide only basic auth, it's expected that all or most users will want to add or modify functionality and development choices in this gem should be made with this in mind.
 
 Though it is not released now, it is planned to have additional functionality available either here or through additional gems (e.g. confirming users, lockable accounts...). The goal here is to provide much of the functionality available in other packages, such as [devise](https://github.com/plataformatec/devise) and [devise_token_auth](https://github.com/lynndylanhurley/devise_token_auth), using JWT.
@@ -25,19 +25,188 @@ $ gem install knock_once
 Mount the gem in our `routes.rb` file:
 
 ```ruby
-mount KnockOnce::Engine, at: '/auth'
+mount KnockOnce::Engine, at: '/auth' # Can mount at whatever path you like
 ```
 
-Then run generators to generate migration
+Then run generators and include the name for your user model
 ```
-rails g knock_once:install
+rails g knock_once:install [User]
 ```
 
+## Setting up
+After you run the install generator, you will have a user model, user migration and an initialization file. You only need to run `rails db:migrate`  to get started, but realistically your user model will have more information than just an email. Add your additional user fields to the migration (and any validations etc you need for them on the model) and then whitelist the required user params in the initializer.
+
+### Require user auth on a controller
+You have access to the `authenticate_user` method via the `knock` gem. The easiest way to incorporate this is to include the module in your application controller:
+```
+class ApplicationController < ActionController::API
+  include Knock::Authenticable
+end
+```
+
+Then you can add the standard before action on each controller you would like to require authentication for: `before_action :authenticate_user`
+
+## User
+
+
+### User validations
+knock_once has basic user validation for the following fields:
+
+* email: must be unique, less than 255 characters and conform to a very basic regext test
+* password: must be at least 8 characters
+*Note:* Password is allowed to be nil on update, but enforced for changes on the controller, so if you decide to override either the user or passwords_controller you can update attributes without changing this validation on the model.
+* password_digest: must be present (fails if you forget to pass a `password_confirmation` on registration)
+
+If you would like to add additional validations, you can do so directly inside the `user.rb` file that is created by the generator.
+
+### User endpoints
+User endpoints are avalailable under `#{mount_path}/users` with the exception of retrieving a token, which is available under `#{mount_path}/user_token`. For example, if you have mounted the engine at `auth` then your user show action is at `/auth/users`.
+
+*Note:* for the rest of the examples it is assumed that you have mounted the engine at `auth`.
+
+#### Registering a new user
+To register a new user `POST` to `/auth/users` with the information required by your application. At a minimum, user registration must include an `email`, `password` and `password confirmation`. 
+
+Example:
+```
+{
+    "email": "exampleuser@example.com",
+    "password": "password",
+    "password_confirmation": "password"
+}
+```
+
+#### Get user token (Login)
+To get a new user token `POST` the user `email` and `password` to `auth/user_token`.
+
+Example:
+```
+{
+	"auth": {
+		"email": "firstuser@example.com",
+		"password": "password"
+	}
+}
+```
+
+#### Returning user info in user token
+By default `knock_once` will only return the user's id and email address when user information is encoded in the token (on login, create token and get user). To overwrite this add the method `to_token_payload` to the `user.rb` model that was created by the generator and define the values you would like to return.
+Example:
+
+```ruby
+def to_token_payload
+  {
+    sub: id,
+    email: email,
+    user_name: user_name,
+    image: image
+  }
+end
+```
+
+#### Get user
+The default show action returns the current user based on the token passed. To retrieve current user information `GET` to `/auth/users` with a valid authorization token.
+
+If you would like to retrieve other users, you can add a controller action and route. If you choose to have this controller inherit from `KnockOnce::UsersController` then there is no need to call `authenticate_user` as it is already called in the engine. A very basic example would be:
+
+`app/controller/users_controller.rb`
+```ruby
+class UsersController < KnockOnce::UsersController
+  def show
+    @user = User.find(params[:id])
+    render json: @user
+  end
+end
+```
+
+`config/routes.rb`
+```ruby
+Rails.application.routes.draw do
+  mount KnockOnce::Engine, at: '/auth'
+
+  post '/users', to: 'users#show'
+end
+```
+
+#### Updating a user
+To update a user attribute(s), `PATCH` or `PUT` to `/auth/users` with a valid token, the `current_password` and the updated attributes.
+
+Example:
+```
+{
+	"current_password": "password",
+	"email": "newemail@example.com"
+}
+```
+
+*Note:* You will need to strip empty fields on the front end. If you pass empty strings as values, they will save as those values (with the exception of `email` which will fail validation).
+
+*Note:* To change a user password, see the passwords section below.
+
+#### Deleting a user
+To delete a user `DELETE` to `/auth/users` with a valid token and the current password.
+
+Example:
+```
+{
+  "current_password": "password",
+}
+```
+
+### Passwords
+Password changes and the forgot password flow are handled by the passwords controller. The passwords controller, like the users controller, enforces that a current password is passed to update. This behavior will be customizable in the future.
+
+#### Updating a user password (when the user knows their current password)
+To update a user password `PATCH` or `PUT` to `/auth/passwords` with a valid authorization token, the `current_password`, the desired new `password` and a matching `password_confirmation`.
+
+Example:
+```
+{
+	"current_password": "password",
+	"password": "newpassword",
+	"password_confirmation": "newpassword"
+}
+```
+
+### Forgot password flow
+To allow the user to reset their password `POST` a valid email to `/auth/passwords/reset`. This will trigger an email which has a token. To select a new password the token must be passed with a `PATCH` or `PUT` to `/auth/passwords/reset` along with a `token`, `password` and `password_confirmation`. There is also a convenience method avalable at `/auth/passwords/validate` which will return an empty `202` if the token passed to it is valid (this though is the only function, it does not reset passwords or invalidate tokens; it only validates that they exist in the database).
+
+#### Creating a token
+To create a token simply `POST` to `/auth/passwords/reset` with a valid email address. As a security precaution, the server will return `200` and a non-commital message regardless of whether the email is registered.
+
+Password Reset tokens are good for 1 hour by default. This can be customized in the initializer.
+
+#### Updating password with token
+To reset a user password with a valid reset token `PATCH` or `PUT` to `/auth/passwords/reset` with the `token`, a `password` and `password_confirmation`.
+
+Example:
+```
+{
+	"token": "t7wHptqkZIGAirwdq5Ubt_rx",
+	"password": "newpassword",
+	"password_confirmation": "newpassword"
+}
+```
+
+#### Validation endpoint
+If you would like to check if a user token is valid (e.g. you are making them enter a pin or copy a token from an email) you can `POST` to `/auth/passwords/validate` with a `token`. This will return an empty `202` on success and `404` on failure.
+
 ## Current state
-The gem has been extracted from a test project and as such has very little configurability (but it works at least within those parameters). The primary next steps are to add user configuration options, additional documentation, add tests for current functionality and improve the generators.
+The gem has been extracted from a test project and as such has only limited configurability (but it works at least within those parameters). The primary next steps are to add user configuration options, additional documentation, add tests for current functionality and improve the generators.
 
 ## Contributing
 Pull requests are very welcome.
 
+Current list of items that I would like to add to the gem
+
+* Tests! The current test suite needs work. Please see [CONTRIBUTING](https://github.com/nicholasshirley/knock_once/contributing.md) for the current test strategy.
+* Initializer that lets user app decide when to require password for on update. Currently the default is for any changes to the user and to change password
+* Initializer + code changes to let users set password recovery method (e.g. token vs pin), length
+* Initializer + code changes to customize what is required on delete (default is a valid token only)
+* Forgot password mail template that generate based on the choosen strategy (e.g. reset link, email token, pin reset...) and the initializers to suppor this
+* Hook into knock initializer so that users can customize those options from the knock_once initializer file
+
+Please see [CONTRIBUTING](https://github.com/nicholasshirley/knock_once/contributing.md) for specicifics.
+
 ## License
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -14,23 +14,9 @@ RDoc::Task.new(:rdoc) do |rdoc|
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
 
-APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
 load 'rails/tasks/engine.rake'
 
-
 load 'rails/tasks/statistics.rake'
 
-
-
 require 'bundler/gem_tasks'
-
-require 'rake/testtask'
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << 'test'
-  t.pattern = 'test/**/*_test.rb'
-  t.verbose = false
-end
-
-
-task default: :test

data/app/controllers/knock_once/passwords_controller.rb

@@ -10,8 +10,10 @@ module KnockOnce
       # if valid user
       if @user
         # generate a new token and save
-        Password.save_token_and_expiry(@user)
-        Password.email_reset(@user.email)
+        password = Password.new(@user)
+        password.email_reset
+        password.save_token_and_expiry
+
         render status: 200, json: {
           message: 'Your request has been received. If we have an email matching that account you will receive link to reset your password.'
         }

data/app/controllers/knock_once/users_controller.rb

@@ -1,4 +1,4 @@
-require_dependency "knock_once/application_controller"
+require_dependency 'knock_once/application_controller'
 
 module KnockOnce
   class UsersController < ApplicationController
@@ -11,7 +11,7 @@ module KnockOnce
     end
 
     def update
-      @user = current_user
+      @user = User.find_by_id(current_user.id)
       if @user.authenticate(params[:current_password])
         if @user.update(user_params)
           render json: {
@@ -28,10 +28,14 @@ module KnockOnce
 
     def destroy
       @user = current_user
-      if @user.destroy
-        render json: :success
+      if @user.authenticate(params[:current_password])
+        if @user.destroy
+          render json: :success
+        else
+          render json: @user.errors.full_messages
+        end
       else
-        render json: @user.errors.full_messages
+        render status: :unprocessable_entity, json: ['Current password is incorrect']
       end
     end
 
@@ -47,7 +51,7 @@ module KnockOnce
     private
 
     def user_params
-      params.permit(:user, :user_name, :email, :current_password, :password, :password_confirmation)
+      params.permit(KnockOnce.configuration.user_params)
     end
   end
 end

data/app/mailers/knock_once/password_reset_mailer.rb

@@ -1,14 +1,14 @@
 module KnockOnce
   class PasswordResetMailer < ApplicationMailer
-    default from: 'no-reply@sporkbook.com'
+    default from: 'no-reply@your_app_name_here.com'
 
     def password_reset(user, token)
       @user = user
       @token = token
 
       mail(
-        to: @user,
-        subject: 'Forgot password request from SporkBook')
+        to: @user.email,
+        subject: 'Forgot password request')
     end
   end
 end

data/app/models/knock_once/password.rb

@@ -1,19 +1,19 @@
 module KnockOnce
-  class Password < ApplicationRecord
-    attr_accessor :token
-    attr_accessor :user
+  class Password
 
-    def self.generate_reset_token
-      @token = SecureRandom.urlsafe_base64(18, false)
-    end
+    attr_accessor :token, :user
 
-    def self.save_token_and_expiry(user)
+    def initialize(user)
+      @token = SecureRandom.urlsafe_base64(KnockOnce.configuration.reset_token_length, false)
       @user = user
-      generate_reset_token
-      User.find_by_email(@user['email']).update_attributes(password_reset_token: @token, password_token_expiry: 1.hour.from_now)
     end
 
-    def self.email_reset(email)
+    def save_token_and_expiry
+      User.find_by_email(@user['email'])
+        .update_attributes(password_reset_token: @token, password_token_expiry: KnockOnce.configuration.password_token_expiry)
+    end
+
+    def email_reset
       PasswordResetMailer.password_reset(@user, @token).deliver_now
     end
   end

data/app/views/knock_once/password_reset_mailer/password_reset.html.erb

@@ -10,9 +10,5 @@
 
       <h2><%= @token %></h2>
     </p>
-
-    <H2>
-      <a href="http://localhost:8080/#/reset">Click here to reset your password</a>
-    </H2>
   </body>
 </html>

data/lib/generators/knock_once/install_generator.rb

@@ -2,17 +2,30 @@ module KnockOnce
   class InstallGenerator < Rails::Generators::Base
     include Rails::Generators::Migration
 
-    source_root File.expand_path("../../../templates", __FILE__)
+    argument :user_class, type: :string, default: "User"
 
+    source_root File.expand_path('../../../templates', __FILE__)
+
+    # Copy initializer into user app
+    def copy_initializer
+      copy_file('create_initializer.rb', 'config/initializers/knock_once.rb')
+    end
+
+    # Copy user information (model & Migrations) into user app
     def create_user_model
-      copy_file('user_model.rb', 'app/models/user.rb')
+      fname = "app/models/#{user_class.underscore}.rb"
+      unless File.exist?(File.join(destination_root, fname))
+        template("user_model.rb", fname)
+      else
+        say_status('skipped', "Model #{user_class.underscore} already exists")
+      end
     end
 
     def copy_migrations
-      if self.class.migration_exists?("db/migrate", "create_knock_once_users")
-        say_status("skipped", "Migration create_knock_once_users already exists")
+      if self.class.migration_exists?('db/migrate', "create_knock_once_#{user_class.underscore}")
+        say_status('skipped', "Migration create_knock_once_#{user_class.underscore} already exists")
       else
-        migration_template("create_knock_once_users.rb.erb", "db/migrate/create_knock_once_users.rb")
+        migration_template('create_knock_once_users.rb.erb', "db/migrate/create_knock_once_#{user_class.pluralize.underscore}.rb")
       end
     end
 

data/lib/knock_once.rb

@@ -1,5 +1,27 @@
 require "knock_once/engine"
 
 module KnockOnce
-  # Your code goes here...
+  class Configuration
+    attr_accessor :user_params
+    attr_accessor :password_token_expiry
+    attr_accessor :reset_token_length
+
+    def initialize
+      @user_params = :user, :email, :current_password, :password, :password_confirmation
+      @password_token_expiry = 1.hour.from_now
+      @reset_token_length = 18
+    end
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configuration=(config)
+    @configuration = config
+  end
+
+  def self.configure
+    yield configuration
+  end
 end

data/lib/knock_once/engine.rb

@@ -4,5 +4,9 @@ module KnockOnce
   class Engine < ::Rails::Engine
     isolate_namespace KnockOnce
     config.generators.api_only = true
+
+    config.generators do |g|
+      g.test_framework :rspec
+    end
   end
 end

data/lib/knock_once/version.rb

@@ -1,3 +1,3 @@
 module KnockOnce
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end

data/lib/templates/create_initializer.rb

@@ -0,0 +1,20 @@
+KnockOnce.configure do |config|
+
+  # WHITELIST USER PARAMS
+
+  # By default knock_once will whitelist :user, :email, :current_password
+  # :password, :password_confirmation
+  # To add your own params push them into the user_param array. Example:
+  # config.user_params.push(:user_name)
+
+  # PASSWORD RESET OPTIONS
+
+  # Reset token validity
+  # By default password tokens will only be valid for one hour.
+  # config.password_token_expiry = 1.hour.from_now
+
+  # Reset token length
+  # By default the reset token length is 18
+  # config.reset_token_length = 18
+
+end

data/lib/templates/create_knock_once_users.rb.erb

@@ -1,6 +1,6 @@
-class CreateKnockOnceUsers < ActiveRecord::Migration<%= "[#{Rails::VERSION::STRING[0..2]}]" if Rails::VERSION::MAJOR > 4 %>
+class CreateKnockOnce<%= user_class.pluralize %> < ActiveRecord::Migration<%= "[#{Rails::VERSION::STRING[0..2]}]" if Rails::VERSION::MAJOR > 4 %>
   def change
-    create_table :users do |t|
+    create_table :<%= user_class.pluralize %> do |t|
       # Required
       t.string :email
       t.string :password_digest
@@ -13,6 +13,6 @@ class CreateKnockOnceUsers < ActiveRecord::Migration<%= "[#{Rails::VERSION::STRI
       t.timestamps
     end
 
-    add_index :users, :email, unique: true
+    add_index <%= user_class.pluralize %>, :email, unique: true
   end
 end

data/lib/templates/user_model.rb

@@ -1,3 +1,3 @@
-class User < KnockOnce::User
+class <%= user_class.capitalize %> < KnockOnce::User
 
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: knock_once
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Nicholas Shirley
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-11-13 00:00:00.000000000 Z
+date: 2017-11-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -16,56 +16,98 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.1.4
+        version: '5.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.1.4
+        version: '5.1'
 - !ruby/object:Gem::Dependency
   name: knock
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: database_cleaner
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: factory_bot_rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '4'
 description: knock_once provides basic user email auth using knock.
 email:
 - nicholas@reallymy.email
@@ -83,13 +125,10 @@ files:
 - app/jobs/knock_once/application_job.rb
 - app/mailers/knock_once/application_mailer.rb
 - app/mailers/knock_once/password_reset_mailer.rb
-- app/mailers/knock_once/user_mailer.rb
 - app/models/knock_once/application_record.rb
 - app/models/knock_once/password.rb
 - app/models/knock_once/user.rb
 - app/views/knock_once/password_reset_mailer/password_reset.html.erb
-- app/views/knock_once/user_mailer/welcome_mailer.html.erb
-- app/views/knock_once/user_mailer/welcome_mailer.text.erb
 - app/views/layouts/knock_once/mailer.html.erb
 - app/views/layouts/knock_once/mailer.text.erb
 - config/initializers/knock.rb
@@ -99,6 +138,7 @@ files:
 - lib/knock_once/engine.rb
 - lib/knock_once/version.rb
 - lib/tasks/knock_once_tasks.rake
+- lib/templates/create_initializer.rb
 - lib/templates/create_knock_once_users.rb.erb
 - lib/templates/user_model.rb
 homepage: https://github.com/nicholasshirley/knock_once

data/app/mailers/knock_once/user_mailer.rb

@@ -1,12 +0,0 @@
-module KnockOnce
-  class UserMailer < ApplicationMailer
-    def welcome_mailer(user)
-      @user = user
-      mail(to: @user.email,
-           subject: 'Welcome to Sporkbook!') do |format|
-             format.html { render 'welcome_mailer' }
-             format.text { render 'welcome_mailer' }
-           end
-    end
-  end
-end

data/app/views/knock_once/user_mailer/welcome_mailer.html.erb

@@ -1 +0,0 @@
-Welcome <%= @user.email %>!

data/app/views/knock_once/user_mailer/welcome_mailer.text.erb

@@ -1 +0,0 @@
-Welcome <%= @user.email %>!