passwordless 0.4.2 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75c3878f6173f614504aec1073969f86c5c62b52f987c2c3402ea75771d705b4
-  data.tar.gz: d5f7d2cbd330c33ac40213860653087a2d8977bcad1d936431fd5c41a03e60e7
+  metadata.gz: a3dbc0b122174ab4d4f115f47ef829bfe0ccfdf49cb559725e8833d5abaef517
+  data.tar.gz: ba545dc28ee08852e3c2caf2c9d920343aac14d2039bd3dc4f48e399d99c8bf4
 SHA512:
-  metadata.gz: 0a1c0c33379fc8da5b45fb26e1bf89d27848be3c0d627bdf84257966cf5256e85c0e5e2129f5da2f39602a8346649d082dc9de1387886110580d1693619df922
-  data.tar.gz: 59528a2ec29c12b02de00616fd9b184b998d20d04124b5dbe08143fe7b9ca77f632395b60ae18052500b5b0ea84d9e4b7307df50200fed2a621d52c893106824
+  metadata.gz: 79e1c14bcc3d71e438f0f7b146642460d3116a3d681a2deb17bc6e860d819b990e68565de94a72caa640fa5958fc9587769b6ee0c6af7b16a2e3bac2475d6605
+  data.tar.gz: 1695fc3178204892a35ee1a35869836b09d26005f4b4e4c99d2e9d02c813a87a1fefad6f00664302f191ecb4f3e3fe9cc57888aeadf2b8a7c6355fb1f1581873

data/Rakefile

@@ -1,22 +1,17 @@
+# frozen_string_literal: true
+
 begin
   require 'bundler/setup'
 rescue LoadError
   puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
 end
 
-require 'rdoc/task'
-
-RDoc::Task.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'Passwordless'
-  rdoc.options << '--line-numbers'
-  rdoc.rdoc_files.include('README.md')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
+require 'yard'
+YARD::Rake::YardocTask.new
+task docs: :yard
 
-APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+APP_RAKEFILE = File.expand_path('../test/dummy/Rakefile', __FILE__)
 load 'rails/tasks/engine.rake'
-
 load 'rails/tasks/statistics.rake'
 
 require 'bundler/gem_tasks'

data/app/controllers/passwordless/application_controller.rb

@@ -1,5 +1,11 @@
+# frozen_string_literal: true
+
 module Passwordless
+  # Base for Passwordless controllers
   class ApplicationController < ::ApplicationController
+    # Always returns true. Use to check if <Some>Controller inherits
+    # from ApplicationController.
+    # @return [boolean]
     def passwordless_controller?
       true
     end

data/app/controllers/passwordless/sessions_controller.rb

@@ -1,22 +1,28 @@
+# frozen_string_literal: true
+
 require 'bcrypt'
 
 module Passwordless
+  # Controller for managing Passwordless sessions
   class SessionsController < ApplicationController
     include ControllerHelpers
 
     helper_method :authenticatable_resource
 
+    # get '/sign_in'
+    #   Assigns an email_field and new Session to be used by new view.
+    #   renders sessions/new.html.erb.
     def new
-      @email_field = authenticatable_class.passwordless_email_field
-
+      @email_field = email_field
       @session = Session.new
     end
 
+    # post '/sign_in'
+    #   Creates a new Session record then sends the magic link
+    #   renders sessions/create.html.erb.
+    # @see Mailer#magic_link Mailer#magic_link
     def create
-      email_field = authenticatable_class.passwordless_email_field
-      email = params.require(:passwordless).fetch(email_field).downcase
-      authenticatable =
-        authenticatable_class.where("lower(#{email_field}) = ?", email).first
+      authenticatable = find_authenticatable
 
       session = Session.new.tap do |us|
         us.remote_addr = request.remote_addr
@@ -31,27 +37,32 @@ module Passwordless
       render
     end
 
+    # get '/sign_in/:token'
+    #   Looks up session record by provided token. Signs in user if a match
+    #   is found. Redirects to either the user's original destination
+    #   or _root_path_
+    # @see ControllerHelpers#sign_in
+    # @see ControllerHelpers#save_passwordless_redirect_location!
     def show
       # Make it "slow" on purpose to make brute-force attacks more of a hassle
       BCrypt::Password.create(params[:token])
 
-      session = Session.valid.find_by!(
-        authenticatable_type: authenticatable_classname,
-        token: params[:token]
-      )
-
+      session = find_session
       sign_in session.authenticatable
 
-      enabled = Passwordless.redirect_back_after_sign_in
-      destination = dest = reset_passwordless_redirect_location!(User)
+      redirect_enabled = Passwordless.redirect_back_after_sign_in
+      destination = reset_passwordless_redirect_location!(User)
 
-      if enabled && destination
-        redirect_to dest
+      if redirect_enabled && destination
+        redirect_to destination
       else
         redirect_to main_app.root_path
       end
     end
 
+    # match '/sign_out', via: %i[get delete].
+    #   Signs user out. Redirects to root_path
+    # @see ControllerHelpers#sign_out
     def destroy
       sign_out authenticatable_class
       redirect_to main_app.root_path
@@ -74,5 +85,22 @@ module Passwordless
     def authenticatable_resource
       authenticatable.pluralize
     end
+
+    def email_field
+      authenticatable_class.passwordless_email_field
+    end
+
+    def find_authenticatable
+      authenticatable_class.where(
+        "lower(#{email_field}) = ?", params[:passwordless][email_field]
+      ).first
+    end
+
+    def find_session
+      Session.valid.find_by!(
+        authenticatable_type: authenticatable_classname,
+        token: params[:token]
+      )
+    end
   end
 end

data/app/mailers/passwordless/mailer.rb

@@ -1,7 +1,12 @@
+# frozen_string_literal: true
+
 module Passwordless
+  # The mailer responsible for sending Passwordless' mails.
   class Mailer < ActionMailer::Base
     default from: Passwordless.default_from_address
 
+    # Sends a magic link (secret token) email.
+    # @param session [Session] A Passwordless Session
     def magic_link(session)
       @session = session
 
@@ -11,7 +16,10 @@ module Passwordless
         send(authenticatable_resource_name).token_sign_in_url(session.token)
 
       email_field = @session.authenticatable.class.passwordless_email_field
-      mail to: @session.authenticatable.send(email_field), subject: "Your magic link ✨"
+      mail(
+        to: @session.authenticatable.send(email_field),
+        subject: 'Your magic link ✨'
+      )
     end
   end
 end

data/app/models/passwordless/application_record.rb

@@ -1,4 +1,7 @@
+# frozen_string_literal: true
+
 module Passwordless
+  # Base record for Passordless' models
   class ApplicationRecord < ActiveRecord::Base
     self.abstract_class = true
   end

data/app/models/passwordless/session.rb

@@ -1,6 +1,11 @@
+# frozen_string_literal: true
+
 module Passwordless
+  # The session responsible for holding the connection between the record
+  # trying to log in and the unique tokens.
   class Session < ApplicationRecord
-    belongs_to :authenticatable, polymorphic: true
+    belongs_to :authenticatable,
+      polymorphic: true, inverse_of: :passwordless_sessions
 
     validates \
       :timeout_at,

data/config/routes.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 Passwordless::Engine.routes.draw do
   get '/sign_in', to: 'sessions#new', as: :sign_in
   post '/sign_in', to: 'sessions#create'

data/db/migrate/20171104221735_create_passwordless_sessions.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class CreatePasswordlessSessions < ActiveRecord::Migration[5.1]
   def change
     create_table :passwordless_sessions do |t|

data/lib/passwordless.rb

@@ -1,10 +1,11 @@
+# frozen_string_literal: true
+
 require 'passwordless/engine'
 require 'passwordless/url_safe_base_64_generator'
 
+# The main Passwordless module
 module Passwordless
   mattr_accessor(:default_from_address) { 'CHANGE_ME@example.com' }
-  mattr_accessor(:token_generator) do
-    UrlSafeBase64Generator.new
-  end
+  mattr_accessor(:token_generator) { UrlSafeBase64Generator.new }
   mattr_accessor(:redirect_back_after_sign_in) { true }
 end

data/lib/passwordless/controller_helpers.rb

@@ -1,5 +1,15 @@
+# frozen_string_literal: true
+
 module Passwordless
+  # Helpers to work with Passwordless sessions from controllers
   module ControllerHelpers
+    # Authenticate a record using cookies. Looks for a cookie corresponding to
+    # the _authenticatable_class_. If found try to find it in the database.
+    # @param authenticatable_class [ActiveRecord::Base] any Model connected to
+    #   passwordless. (e.g - _User_ or _Admin_).
+    # @return [ActiveRecord::Base|nil] an instance of Model found by id stored
+    #   in cookies.encrypted or nil if nothing is found.
+    # @see ModelHelpers#passwordless_with
     def authenticate_by_cookie(authenticatable_class)
       key = cookie_name(authenticatable_class)
       authenticatable_id = cookies.encrypted[key]
@@ -8,22 +18,39 @@ module Passwordless
       authenticatable_class.find_by(id: authenticatable_id)
     end
 
+    # Signs in user by assigning their id to a permanent cookie.
+    # @param authenticatable [ActiveRecord::Base] Instance of Model to sign in
+    #   (e.g - @user when @user = User.find(id: some_id)).
+    # @return [ActiveRecord::Base] the record that is passed in.
     def sign_in(authenticatable)
       key = cookie_name(authenticatable.class)
       cookies.encrypted.permanent[key] = { value: authenticatable.id }
       authenticatable
     end
 
+    # Signs out user by deleting their encrypted cookie.
+    # @param (see #authenticate_by_cookie)
+    # @return [boolean] Always true
     def sign_out(authenticatable_class)
       key = cookie_name(authenticatable_class)
       cookies.encrypted.permanent[key] = { value: nil }
       cookies.delete(key)
+      true
     end
 
+    # Saves request.original_url as the redirect location for a
+    # passwordless Model.
+    # @param (see #authenticate_by_cookie)
+    # @return [String] the redirect url that was just saved.
     def save_passwordless_redirect_location!(authenticatable_class)
       session[session_key(authenticatable_class)] = request.original_url
     end
 
+    # Resets the redirect_location to root_path by deleting the redirect_url
+    # from session.
+    # @param (see #authenticate_by_cookie)
+    # @return [String, nil] the redirect url that was just deleted,
+    #   or nil if no url found for given Model.
     def reset_passwordless_redirect_location!(authenticatable_class)
       session.delete session_key(authenticatable_class)
     end

data/lib/passwordless/engine.rb

@@ -1,4 +1,7 @@
+# frozen_string_literal: true
+
 module Passwordless
+  # Engine that runs the passwordless gem.
   class Engine < ::Rails::Engine
     isolate_namespace Passwordless
 

data/lib/passwordless/model_helpers.rb

@@ -1,6 +1,14 @@
+# frozen_string_literal: true
+
 module Passwordless
+  # Some helpers for models that can sign in passswordlessly.
   module ModelHelpers
+    # Creates relationship - has_many :passwordless_sessions
+    # Defines a method `Class.passwordless_email_field` returning its email
+    #   field name (e.g. `:email`)
+    # @param field [string] email submitted by user.
     def passwordless_with(field)
+      has_many :passwordless_sessions, class_name: 'Passwordless::Session'
       define_singleton_method(:passwordless_email_field) { field }
     end
   end

data/lib/passwordless/router_helpers.rb

@@ -1,5 +1,21 @@
+# frozen_string_literal: true
+
 module Passwordless
+  # Helpers for generating passwordless routes.
   module RouterHelpers
+    # Generates passwordless routes for a given Model
+    #   Example usage:
+    #     passwordless_for :users
+    #     # or with options ...
+    #     passwordless_for :users, at: 'session_stuff', as: :user_session_things
+    # @param resource [Symbol] the pluralized symbol of a Model (e.g - :users).
+    # @param at [String] Optional - provide custom path for the passwordless
+    #   engine to get mounted at (using the above example your URLs end
+    #   up like: /session_stuff/sign_in). (Default: resource.to_s)
+    # @param as [Symbol] Optional - provide custom scope for url
+    #   helpers (using the above example in a view:
+    #   <%= link_to 'Sign in', user_session_things.sign_in_path %>).
+    #   (Default: resource.to_s)
     def passwordless_for(resource, at: nil, as: nil)
       mount(
         Passwordless::Engine,

data/lib/passwordless/url_safe_base_64_generator.rb

@@ -1,5 +1,13 @@
+# frozen_string_literal: true
+
 module Passwordless
+  # Generates random numbers for Session records
   class UrlSafeBase64Generator
+    # Passwordless' default random string strategy. Generates a url safe
+    # base64 random string.
+    # @param _session [Session] Optional - Passwordless passes the sesion Record
+    # to generators so you can (optionally) use it for generating your tokens.
+    # @return [String] 32 byte base64 string
     def call(_session)
       SecureRandom.urlsafe_base64(32)
     end

data/lib/passwordless/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Passwordless
-  VERSION = '0.4.2'
+  VERSION = '0.4.3' # :nodoc:
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: passwordless
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.4.3
 platform: ruby
 authors:
 - Mikkel Malmberg
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-12-24 00:00:00.000000000 Z
+date: 2017-12-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -52,7 +52,35 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Description of Passwordless.
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
 email:
 - mikkel@brnbw.com
 executables: []
@@ -79,7 +107,6 @@ files:
 - lib/passwordless/router_helpers.rb
 - lib/passwordless/url_safe_base_64_generator.rb
 - lib/passwordless/version.rb
-- lib/tasks/passwordless_tasks.rake
 homepage: https://github.com/mikker/passwordless
 licenses:
 - MIT
@@ -103,5 +130,5 @@ rubyforge_project:
 rubygems_version: 2.7.3
 signing_key: 
 specification_version: 4
-summary: Summary of Passwordless.
+summary: Add authentication to your app without all the ickyness of passwords.
 test_files: []

data/lib/tasks/passwordless_tasks.rake

@@ -1,4 +0,0 @@
-# desc "Explaining what the task does"
-# task :passwordless do
-#   # Task goes here
-# end