devise-passwordless 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08511edac883e2b94811e349d41ce761a7d5771e55b628450bd1e02d835f0374'
-  data.tar.gz: 9d0f442ffed9f59818a370c8bdc815f362367bd24a6c09fc66b0097009992cd9
+  metadata.gz: a9bb24b5fe4c2794fc255797ca018533757e999c80ef5ac8f2992e245b48bec1
+  data.tar.gz: c38c95a39eaae489078f4730f96c4dd8ebda460028cd2ef752196396e2b35837
 SHA512:
-  metadata.gz: 405e6a4ee5dbb3c66dcd079a92642e01dfb10b336d5e220f8a05f0814a2ac50ef47e78aa13e734b4aec4ce2891eb8cde900854984c3c84193afb1ff05e5b8481
-  data.tar.gz: 933e273120b795b3b1eb1bb96a4672c9f3da7645ed7df55046eddc57197307afd9aadee5612fb047980cceed3fc5c2348f5388bb5b19df87191e9ee57e2fdb0f
+  metadata.gz: 821b144072819bf40fdc6687184262af929cfc066173700b7afdb92a56a344e6c01c923bd956a3ae928c8dab572f8ff2f84de73c56fde29139e2c28f8564fe0c
+  data.tar.gz: 51bc2079671c704e365e43b7ad10d72359b8ff2588c31deee1ab001ab2f93f4d6fe3992a1de7ea890401dbf1be08ae912e4302fd7c673b6b61bc3ba29832faae

data/README.md

@@ -1,42 +1,43 @@
 # Devise::Passwordless
 
-A passwordless login strategy for [Devise][]
+A passwordless a.k.a. "magic link" login strategy for [Devise][]
+
+No database migrations are needed as login links are stateless, encrypted tokens generated with Rails's MessageEncryptor.
 
 ## Installation
 
-You should already have Devise installed. Then add this gem:
+First, install and set up [Devise][].
+
+Then add this gem to your application's Gemfile:
 
 ```ruby
 gem "devise-passwordless"
 ```
 
-Then run the generator to automatically update your Devise initializer:
+And then execute:
 
 ```
-rails g devise:passwordless:install
+$ bundle install
 ```
 
-Merge these YAML values into your `devise.en.yml` file:
+Finally, run the install generator:
 
-```yaml
-en:
-  devise:
-    failure:
-      passwordless_invalid: "Invalid or expired login link."
-    mailer:
-      passwordless_link:
-        subject: "Here's your magic link"
+```
+$ rails g devise:passwordless:install
 ```
 
+See the [customization section](#customization) for details on what gets installed and how to configure and customize.
+
 ## Usage
 
-This gem adds an `:email_authenticatable` strategy that can be used in your Devise models for passwordless authentication. This strategy plays well with most other Devise strategies.
+This gem adds an `:magic_link_authenticatable` strategy that can be used in your Devise models for passwordless authentication. This strategy plays well with most other Devise strategies (see [*notes on other Devise strategies*](#notes-on-other-devise-strategies)).
 
-For example, for a User model, you could do this (other strategies optional and not an exhaustive list):
+For example, for a User model, you could do this (other strategies listed are optional and not exhaustive):
 
 ```ruby
+# app/models/user.rb
 class User < ApplicationRecord
-  devise :email_authenticatable,
+  devise :magic_link_authenticatable,
          :registerable,
          :rememberable,
          :validatable,
@@ -44,7 +45,81 @@ class User < ApplicationRecord
 end
 ```
 
-**Note** if using the `:rememberable` strategy for "remember me" functionality, you'll need to add a `remember_token` column to your resource, as there is no password salt to use for validating cookies:
+Then, you'll need to generate two controllers to modify Devise's default session create logic and to handle processing magic links:
+
+```
+$ rails g devise:passwordless:controller User
+```
+
+Then, modify your routes file like so to use these controllers:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  devise_for :users, controllers: { sessions: "users/sessions" }
+  devise_scope :user do
+    get "/users/magic_links" => "users/magic_links#show"
+  end
+end
+```
+
+Finally, you'll want to update Devise's generated views to remove references to passwords.
+
+These files/directories can be deleted entirely:
+
+* `app/views/devise/passwords`
+* `app/views/devise/mailer/password_change.html.erb`
+* `app/views/devise/mailer/reset_password_instructions.html.erb`
+
+And these should be edited to remove password references:
+
+* `app/views/devise/registrations/new.html.erb`
+  * Delete fields `:password` and `:password_confirmation`
+* `app/views/devise/registrations/edit.html.erb`
+  * Delete fields `:password`, `:password_confirmation`, `:current_password`
+* `app/views/devise/sessions/new.html.erb`
+  * Delete field `:password`
+
+## Customization
+
+Configuration options are stored in Devise's initializer at `config/initializers/devise.rb`:
+
+```ruby
+# ==> Configuration for :magic_link_authenticatable
+
+# Need to use a custom Devise mailer in order to send magic links
+config.mailer = "PasswordlessMailer"
+
+# Time period after a magic login link is sent out that it will be valid for.
+# config.passwordless_login_within = 20.minutes
+
+# The secret key used to generate passwordless login tokens. The default value
+# is nil, which means defer to Devise's `secret_key` config value. Changing this
+# key will render invalid all existing passwordless login tokens. You can
+# generate your own secret value with e.g. `rake secret`
+# config.passwordless_secret_key = nil
+```
+
+To customize the magic link email subject line and other status and error messages, modify these values in `config/locales/devise.en.yml`:
+
+```yaml
+en:
+  devise:
+    passwordless:
+      not_found_in_database: "Could not find a user for that email address"
+      magic_link_sent: "A login link has been sent to your email address. Please follow the link to log in to your account."
+    failure:
+      passwordless_invalid: "Invalid or expired login link."
+    mailer:
+      magic_link:
+        subject: "Here's your magic login link 🪄✨"
+```
+
+To customize the magic link email body, edit `app/views/devise/mailer/magic_link.html.erb`
+
+### Notes on other Devise strategies
+
+If using the `:rememberable` strategy for "remember me" functionality, you'll need to add a `remember_token` column to your resource, as by default it assumes you're using a password strategy and relies on comparing the password's salt to validate cookies:
 
 ```ruby
 change_table :users do |t|
@@ -52,9 +127,7 @@ change_table :users do |t|
 end
 ```
 
-**Note** if using the `:confirmable` strategy, you may want to override the default Devise behavior of requiring a fresh login after email confirmation (e.g. [this](https://stackoverflow.com/a/39010334/215168) or [this](https://stackoverflow.com/a/25865526/215168) approach). Otherwise, users will have to get a fresh login link after confirming their email, which makes no sense if they just confirmed they own the email address.
-
-## Configuration
+If using the `:confirmable` strategy, you may want to override the default Devise behavior of requiring a fresh login after email confirmation (e.g. [this](https://stackoverflow.com/a/39010334/215168) or [this](https://stackoverflow.com/a/25865526/215168) approach). Otherwise, users will have to get a fresh login link after confirming their email, which makes little sense if they just confirmed they own the email address.
 
 ## License
 

data/lib/devise/models/{email_authenticatable.rb → magic_link_authenticatable.rb}

@@ -1,8 +1,8 @@
-require 'devise/strategies/email_authenticatable'
+require 'devise/strategies/magic_link_authenticatable'
 
 module Devise
   module Models
-    module EmailAuthenticatable
+    module MagicLinkAuthenticatable
       extend ActiveSupport::Concern
 
       def password_required?
@@ -14,27 +14,32 @@ module Devise
         nil
       end
 
+      def send_magic_link(remember_me)
+        token = Devise::Passwordless::LoginToken.encode(self)
+        send_devise_notification(:magic_link, token, remember_me, {})
+      end
+
       # A callback initiated after successfully authenticating. This can be
       # used to insert your own logic that is only run after the user successfully
       # authenticates.
       #
       # Example:
       #
-      #   def after_passwordless_authentication
+      #   def after_magic_link_authentication
       #     self.update_attribute(:invite_code, nil)
       #   end
       #
-      def after_passwordless_authentication
+      def after_magic_link_authentication
       end
 
       protected
 
       module ClassMethods
         # We assume this method already gets the sanitized values from the
-        # EmailAuthenticatable strategy. If you are using this method on
+        # MagicLinkAuthenticatable strategy. If you are using this method on
         # your own, be sure to sanitize the conditions hash to only include
         # the proper fields.
-        def find_for_email_authentication(conditions)
+        def find_for_magic_link_authentication(conditions)
           find_for_authentication(conditions)
         end
 

data/lib/devise/passwordless.rb

@@ -1,3 +1,3 @@
 require "devise/passwordless/version"
-require "devise/models/email_authenticatable"
+require "devise/models/magic_link_authenticatable"
 require "generators/devise/passwordless/install_generator"

data/lib/devise/passwordless/version.rb

@@ -1,5 +1,5 @@
 module Devise
   module Passwordless
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/devise/strategies/{email_authenticatable.rb → magic_link_authenticatable.rb}

@@ -6,7 +6,7 @@ require "devise/passwordless/login_token"
 
 module Devise
   module Strategies
-    class EmailAuthenticatable < Authenticatable
+    class MagicLinkAuthenticatable < Authenticatable
       #undef :password
       #undef :password=
       attr_accessor :token
@@ -31,7 +31,7 @@ module Devise
         resource = mapping.to.find_by(id: data["resource"]["key"])
         if validate(resource)
           remember_me(resource)
-          resource.after_passwordless_authentication
+          resource.after_magic_link_authentication
           success!(resource)
         else
           fail!(:passwordless_invalid)
@@ -52,12 +52,11 @@ module Devise
   end
 end
 
-Warden::Strategies.add(:email_authenticatable, Devise::Strategies::EmailAuthenticatable)
+Warden::Strategies.add(:magic_link_authenticatable, Devise::Strategies::MagicLinkAuthenticatable)
 
-Devise.add_module(:email_authenticatable, {
+Devise.add_module(:magic_link_authenticatable, {
   strategy: true,
   controller: :sessions,
-  model: "devise/models/email_authenticatable",
-  #route: { email_authenticatable: [nil, :new, :edit] }
-  route: :session
+  route: :session,
+  model: "devise/models/magic_link_authenticatable",
 })

data/lib/generators/devise/passwordless/controller_generator.rb

@@ -0,0 +1,21 @@
+require "rails/generators/named_base"
+
+module Devise::Passwordless
+  module Generators # :nodoc:
+    class ControllerGenerator < ::Rails::Generators::NamedBase # :nodoc:
+      desc "Creates the session and magic link controllers needed for a Devise resource to use passwordless auth"
+
+      def self.default_generator_root
+        File.dirname(__FILE__)
+      end
+
+      def create_sessions_controller
+        template "sessions_controller.rb.erb", File.join("app/controllers", class_path, plural_name, "sessions_controller.rb")
+      end
+
+      def create_magic_links_controller
+        template "magic_links_controller.rb.erb", File.join("app/controllers", class_path, plural_name, "magic_links_controller.rb")
+      end
+    end
+  end
+end

data/lib/generators/devise/passwordless/install_generator.rb

@@ -2,40 +2,83 @@ require "rails/generators"
 require "yaml"
 
 module Devise::Passwordless
-  module Generators
-    class InstallGenerator < ::Rails::Generators::Base
-      desc "Updates the Devise initializer to add passwordless config options"
+  module Generators # :nodoc:
+    class InstallGenerator < ::Rails::Generators::Base # :nodoc:
+      desc "Creates default install and config files for the Devise passwordless auth strategy"
 
       def update_devise_initializer
         inject_into_file 'config/initializers/devise.rb', before: /^end$/ do <<~'CONFIG'.indent(2)
 
-          # ==> Configuration for :email_authenticatable
+          # ==> Configuration for :magic_link_authenticatable
+
+          # Need to use a custom Devise mailer in order to send magic links
+          config.mailer = "PasswordlessMailer"
 
           # Time period after a magic login link is sent out that it will be valid for.
           # config.passwordless_login_within = 20.minutes
-        
-          # The secret key used to generate passwordless login tokens. The default
-          # value is nil, which means defer to Devise's `secret_key` config value.
-          # Changing this key will render invalid all existing passwordless login
-          # tokens. You can generate your own value with e.g. `rake secret`
+
+          # The secret key used to generate passwordless login tokens. The default value
+          # is nil, which means defer to Devise's `secret_key` config value. Changing this
+          # key will render invalid all existing passwordless login tokens. You can
+          # generate your own secret value with e.g. `rake secret`
           # config.passwordless_secret_key = nil
         CONFIG
         end
       end
 
+      def add_custom_devise_mailer
+        create_file "app/mailers/passwordless_mailer.rb" do <<~'FILE'
+        class PasswordlessMailer < Devise::Mailer
+          def magic_link(record, token, remember_me, opts = {})
+            @token = token
+            @remember_me = remember_me
+            devise_mail(record, :magic_link, opts)
+          end
+        end
+        FILE
+        end
+      end
+
+      def add_mailer_view
+        create_file "app/views/devise/mailer/magic_link.html.erb" do <<~'FILE'
+          <p>Hello <%= @resource.email %>!</p>
+
+          <p>You can login using the link below:</p>
+          
+          <p><%= link_to "Log in to my account", send("#{@scope_name.to_s.pluralize}_magic_links_url", Hash[@scope_name, {email: @resource.email, token: @token, remember_me: @remember_me}]) %></p>
+          
+          <p>Note that the link will expire in <%= Devise.passwordless_login_within.inspect %>.</p>          
+        FILE
+        end
+      end
+
       def update_devise_yaml
         devise_yaml = "config/locales/devise.en.yml"
         begin
           config = YAML.load_file(devise_yaml)
         rescue Errno::ENOENT
-          STDERR.puts "Couldn't find devise.en.yml - skipping patch"
+          STDERR.puts "Couldn't find #{devise_yaml} - skipping patch"
           return
         end
-        config["en"]["devise"]["failure"]["passwordless_invalid"] = "Invalid or expired login link."
-        config["en"]["devise"]["mailer"]["passwordless_link"] = {subject: "Your login link"}
-        File.open(devise_yaml, "w") do |f|
-          f.write(config.to_yaml)
-        end
+        config.deep_merge!({
+          en: {
+            devise: {
+              passwordless: {
+                not_found_in_database: "Could not find a user for that email address",
+                magic_link_sent: "A login link has been sent to your email address. Please follow the link to log in to your account.",
+              },
+              failure: {
+                passwordless_invalid: "Invalid or expired login link.",
+              },
+              mailer: {
+                magic_link: {
+                  subject: "Here's your login link 🪄✨",
+                },
+              }
+            }
+          }
+        })
+        File.open(devise_yaml, "w"){ |f| f.write(config.to_yaml) }
       end
     end
   end

data/lib/generators/devise/passwordless/templates/magic_links_controller.rb.erb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+<% module_namespacing do -%>
+class <%= class_name.pluralize %>::MagicLinksController < DeviseController
+  prepend_before_action :require_no_authentication, only: :show
+  prepend_before_action :allow_params_authentication!, only: :show
+  prepend_before_action(only: [:show]) { request.env["devise.skip_timeout"] = true }
+
+  def show
+    self.resource = warden.authenticate!(auth_options)
+    set_flash_message!(:notice, :signed_in)
+    sign_in(resource_name, resource)
+    yield resource if block_given?
+    redirect_to after_sign_in_path_for(resource)
+  end
+
+  protected
+
+  def auth_options
+    { scope: resource_name, recall: "#{resource_name.to_s.pluralize}/sessions#new" }
+  end
+
+  def translation_scope
+    "devise.sessions"
+  end
+
+  private
+
+  def create_params
+    resource_params.permit(:email, :remember_me)
+  end
+end
+<% end -%>

data/lib/generators/devise/passwordless/templates/sessions_controller.rb.erb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+<% module_namespacing do -%>
+class <%= class_name.pluralize %>::SessionsController < Devise::SessionsController
+  def create
+    self.resource = resource_class.find_by(email: create_params[:email])
+    if self.resource
+      resource.send_magic_link(create_params[:remember_me])
+      set_flash_message(:notice, :magic_link_sent, now: true)
+    else
+      set_flash_message(:alert, :not_found_in_database, now: true)
+    end
+
+    self.resource = resource_class.new(create_params)
+    render :new
+  end
+
+  protected
+
+  def translation_scope
+    if action_name == "create"
+      "devise.passwordless"
+    else
+      super
+    end
+  end
+
+  private
+
+  def create_params
+    resource_params.permit(:email, :remember_me)
+  end
+end
+<% end -%>

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: devise-passwordless
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Abe Voelker
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-11-09 00:00:00.000000000 Z
+date: 2020-11-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: devise
@@ -97,13 +97,15 @@ files:
 - bin/console
 - bin/setup
 - devise-passwordless.gemspec
-- lib/devise/models/email_authenticatable.rb
+- lib/devise/models/magic_link_authenticatable.rb
 - lib/devise/passwordless.rb
 - lib/devise/passwordless/login_token.rb
-- lib/devise/passwordless/mailer.rb
 - lib/devise/passwordless/version.rb
-- lib/devise/strategies/email_authenticatable.rb
+- lib/devise/strategies/magic_link_authenticatable.rb
+- lib/generators/devise/passwordless/controller_generator.rb
 - lib/generators/devise/passwordless/install_generator.rb
+- lib/generators/devise/passwordless/templates/magic_links_controller.rb.erb
+- lib/generators/devise/passwordless/templates/sessions_controller.rb.erb
 homepage: https://github.com/abevoelker/devise-passwordless
 licenses:
 - MIT

data/lib/devise/passwordless/mailer.rb

@@ -1,9 +0,0 @@
-if defined?(Devise::Mailer)
-  Devise::Mailer.class_eval do
-    def passwordless_link(record, remember_me, opts = {})
-      @remember_me = remember_me
-      @token = Devise::Passwordless::LoginToken.encode(record)
-      devise_mail(record, :passwordless_link, opts)
-    end
-  end
-end