devise-passwordless 0.7.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4d3b59e8b6d694c28b8e7c92b3b2ce7d98a7e5e9e56465507f23f1b1877dd6a
-  data.tar.gz: f92dee4b5e717eefad98c69ff5920abc6ecda078911fb0abf0ca922c394d1109
+  metadata.gz: 8c2ccc142bc114ca58125c72ea17c9646a6bd602d2a70e99de49b6412df12950
+  data.tar.gz: 7682b97e852e56559ef5babf8bf4f9e0c323083a32b3e16f8d932976e3204aea
 SHA512:
-  metadata.gz: 6af729d1e068eca1b204a32b9944e893c13b5af2c2cced3ae619c94cc19203ca58f5ee30a2911f8e45541ab5e1c7f685dfea0f3a8867065ba76af3b92b58b99b
-  data.tar.gz: b7a87a3d7e8bc28a8ca3d4737ca7093a1d8ac7faac14d1cdb04c163fc9b9d3b6fd8d9f2dc2be3fbf5f80830445c8f7a310a9b3c2bcc5ddfc431b9f836f7cd0bf
+  metadata.gz: 4ac233d2eff38815cca3fadbe0c5b84e919b6129e7e763f30fb18cb5e75b095d10362126e8448fed612dad292463a997d82b36c8ffcb8b95252aacc20db5e46d
+  data.tar.gz: 4feb6345e80a8f2a0ea37527f7926cbff412e70a6bfda8a35166cc686f7eef0bb28d8a63a3702c59ac5ccbba308ca2386ec86e083d748e57bd6fdcdd176f49b1

data/CHANGELOG.md

@@ -0,0 +1,44 @@
+## 1.0.0
+
+### Enhancements
+
+* Tokenization encoding/decoding is now fully customizable
+* Tokenizer encoding now supports extra metadata ([#27] - thanks [@fastjames] and [@elucid]!)
+* Tokenizer encoding now supports `:expires_at` option ([#19], [#21] - thanks [@joeyparis] / [@JoeyLeadJig] and [@bvsatyaram]!)
+* Turbo is now properly supported ([#23], [#33] - thanks [@iainbeeston] and [@til]!)
+* Signed GlobalID tokenization supported ([#22])
+* Concurrent use of password auth (`:database_authenticatable` strategy) now supported ([#13] - thanks [@fschwahn]!)
+* `Devise.paranoid` is now respected with new ambiguous messaging i18n option `:magic_link_sent_paranoid` following ([#36] - thanks [@cbldev]!)
+* More thorough integration testing using a dummy Rails app
+* Added a Rails engine to solve loading issues and tidy up file structuring
+* `Passwordless::SessionsController` now uses gem source instead of needing to be generated from a template
+* `MagicLinksController` no longer requires a weird `routes.rb` entry to work
+* `MagicLinksController` now uses gem source instead of needing to be generated from a template
+* `magic_link_(path|url)` view helpers are now implemented for all resources (cleans up mailer view template)
+* Users will be redirected after magic link is sent (customized using `after_magic_link_sent_path_for`)
+* A warning will be logged if Rails's `filter_parameters` doesn't filter `:token`s from request logs
+
+### Bugfixes
+
+* Autoloading issues related to `uninitialized constant` (e.g.
+  `Devise::Passwordless::Mailer`) should now be fixed
+
+
+[@bvsatyaram]: https://github.com/bvsatyaram
+[@cbldev]: https://github.com/cbldev
+[@fastjames]: https://github.com/fastjames
+[@fschwahn]: https://github.com/fschwahn
+[@elucid]: https://github.com/elucid
+[@iainbeeston]: https://github.com/iainbeeston
+[@joeyparis]: https://github.com/joeyparis
+[@JoeyLeadJig]: https://github.com/JoeyLeadJig
+[@til]: https://github.com/til
+
+[#13]: https://github.com/abevoelker/devise-passwordless/issues/13
+[#19]: https://github.com/abevoelker/devise-passwordless/pull/19
+[#21]: https://github.com/abevoelker/devise-passwordless/pull/21
+[#22]: https://github.com/abevoelker/devise-passwordless/issues/22
+[#23]: https://github.com/abevoelker/devise-passwordless/pull/23
+[#27]: https://github.com/abevoelker/devise-passwordless/pull/27
+[#33]: https://github.com/abevoelker/devise-passwordless/pull/33
+[#36]: https://github.com/abevoelker/devise-passwordless/pull/36

data/README.md

@@ -1,14 +1,25 @@
 # Devise::Passwordless
 
-A passwordless a.k.a. "magic link" login strategy for [Devise][]
+A passwordless login strategy for [Devise] using emailed magic links
 
 ## Features
 
-* No special database migrations needed - magic links are stateless encrypted tokens
-* Magic links are sent from your app - not a mounted Rails engine - so path and URL helpers work as expected
+* No passwords - users receive magic link emails to register / sign-in
+* No database changes needed - magic links are stateless tokens
+* [Choose your token encoding algorithm or easily write your own](#tokenizers)
+* [Can be combined with traditional password authentication in the same model](#combining-password-and-passwordless-auth-in-the-same-model)
 * [Supports multiple user (resource) types](#multiple-user-resource-types)
 * All the goodness of Devise!
 
+## 0.x to 1.0 Upgrade
+
+⭐ The 1.0 release includes significant breaking changes! ⭐
+
+If you're upgrading from 0.x to 1.0, read [the upgrade guide][] for
+a list of changes you'll need to make.
+
+[the upgrade guide]: https://github.com/abevoelker/devise-passwordless/blob/master/UPGRADING.md
+
 ## Installation
 
 First, install and set up [Devise][].
@@ -35,7 +46,7 @@ See the [customization section](#customization) for details on what gets install
 
 ## Usage
 
-This gem adds a `: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)).
+This gem adds a `: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 [*compatibility with other Devise strategies*](#compatibility-with-other-devise-strategies)).
 
 For example, if your Devise model is User, enable the strategy like this:
 
@@ -46,48 +57,43 @@ class User < ApplicationRecord
 end
 ```
 
-Then, you'll need to set up your Devise routes like so to use the passwordless controllers to modify Devise's default session create logic and to handle processing magic links:
+Then, change your route to process sessions using the passwordless sessions controller:
 
 ```ruby
 # config/routes.rb
 Rails.application.routes.draw do
   devise_for :users,
     controllers: { sessions: "devise/passwordless/sessions" }
-  devise_scope :user do
-    get "/users/magic_link",
-      to: "devise/passwordless/magic_links#show",
-      as: "users_magic_link"
-  end
 end
 ```
 
-Finally, you'll want to update Devise's generated views to remove references to passwords, since you don't need them any more!
+Finally, we need to update Devise's views to remove references to passwords. We will assume you're using the standard Devise views for all your registrations and logins; if you need to support multiple Devise models, some with passwordless login and some with password login, then jump down to the [multiple users section below](#multiple-user-resource-types).
+
+First, ensure you have Devise views generated for your project under `app/views/devise`. If not, you can generate them with:
 
-These files/directories can be deleted entirely:
+```
+rails generate devise:views
+```
+
+Then, delete these files and directories:
 
 ```
-app/views/devise/passwords
-app/views/devise/mailer/password_change.html.erb
-app/views/devise/mailer/reset_password_instructions.html.erb
+rm -rf app/views/devise/passwords
+rm -f app/views/devise/mailer/password_change.html.erb
+rm -f app/views/devise/mailer/reset_password_instructions.html.erb
 ```
 
-And these should be edited to remove password references:
+Then, edit these files to remove password references:
 
-* `app/views/devise/registrations/new.html.erb`
+* app/views/devise/registrations/new.html.erb
   * Delete fields `:password` and `:password_confirmation`
-* `app/views/devise/registrations/edit.html.erb`
+* app/views/devise/registrations/edit.html.erb
   * Delete fields `:password`, `:password_confirmation`, `:current_password`
-* `app/views/devise/sessions/new.html.erb`
+* app/views/devise/sessions/new.html.erb
   * Delete field `:password`
 
-#### Manually sending magic links
-
-You can very easily send a magic link at any point like so:
-
-```ruby
-remember_me = true
-User.send_magic_link(remember_me)
-```
+That's it! 🎉 Now check out the customization section so that you
+may change the default configuration to better match your needs.
 
 ## Customization
 
@@ -96,10 +102,14 @@ Configuration options are stored in Devise's initializer at `config/initializers
 ```ruby
 # ==> Configuration for :magic_link_authenticatable
 
-# Need to use a custom Devise mailer in order to send magic links
-require "devise/passwordless/mailer"
+# Need to use a custom Devise mailer in order to send magic links.
+# If you're already using a custom mailer just have it inherit from
+# Devise::Passwordless::Mailer instead of Devise::Mailer
 config.mailer = "Devise::Passwordless::Mailer"
 
+# Which algorithm to use for tokenizing magic links. See README for descriptions
+config.passwordless_tokenizer = "SignedGlobalIDTokenizer"
+
 # Time period after a magic login link is sent out that it will be valid for.
 # config.passwordless_login_within = 20.minutes
 
@@ -115,6 +125,32 @@ config.mailer = "Devise::Passwordless::Mailer"
 # config.passwordless_expire_old_tokens_on_sign_in = false
 ```
 
+Most config options can be set on a per-model basis. For instance,
+you can use different tokenizers across different models like so:
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  devise :magic_link_authenticatable
+
+  def self.passwordless_tokenizer
+    "SignedGlobalIDTokenizer"
+  end
+end
+
+# app/models/another_user.rb
+class AnotherUser < ApplicationRecord
+  devise :magic_link_authenticatable
+
+  def self.passwordless_tokenizer
+    "MessageEncryptorTokenizer"
+  end
+  def self.passwordless_login_within
+    1.hour
+  end
+end
+```
+
 To customize the magic link email subject line and other status and error messages, modify these values in `config/locales/devise.en.yml`:
 
 ```yaml
@@ -123,6 +159,7 @@ en:
     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."
+      magic_link_sent_paranoid: "If your account exists, you will receive an email with a login link. Please follow the link to log in to your account."
     failure:
       magic_link_invalid: "Invalid or expired login link."
     mailer:
@@ -130,9 +167,171 @@ en:
         subject: "Here's your magic login link ✨"
 ```
 
+**Note**: If [Devise's paranoid mode][] is enabled in your Devise initializer, the
+`:magic_link_sent_paranoid` message will be used both when a user account exists
+and when it does not exist to prevent account enumeration vulnerabilities. If
+paranoid mode is disabled, then `:magic_link_sent` will be used for existing
+accounts, and `:not_found_in_database` when no account was found.
+
+[Devise's paranoid mode]: https://github.com/heartcombo/devise/wiki/How-To:-Using-paranoid-mode,-avoid-user-enumeration-on-registerable
+
 To customize the magic link email body, edit `app/views/devise/mailer/magic_link.html.erb`
 
-### Multiple user (resource) types
+## Manually creating and sending magic links
+
+Magic links are created and sent normally using Devise's views for sign-in and registration, but you can create them manually as well.
+
+To send a magic link email, do this:
+
+```ruby
+user = User.last
+user.send_magic_link
+# additional options are passed through to Devise's mailer logic
+user.send_magic_link(remember_me: true, subject: "Custom email subject", "X-Entity-Ref-ID": SecureRandom.uuid)
+```
+
+If you only need to generate the token portion of a magic link, you can do this:
+
+```ruby
+# see the tokenizer's #encode method for all supported keyword options
+token = user.encode_passwordless_token(expires_at: 2.hours.from_now)
+```
+
+Or, to generate the full magic link URL, use this URL view helper:
+
+```ruby
+user_magic_link_url(
+  user: {
+    email: user.email,
+    token: token,
+    remember_me: true
+  }
+)
+```
+
+## Redirecting after magic link is sent
+
+After a user enters their email on the sign-in page, and a magic link is sent, the user
+will be redirected back to the `:root` path of the application.
+
+To provide a custom redirect location, you can write a custom
+`after_magic_link_sent_path_for` helper, similar to
+[how Devise's `after_sign_in_path_for` helper works][after_sign_in_path_for]:
+
+```ruby
+class ApplicationController < ActionController::Base
+  def after_magic_link_sent_path_for(resource_or_scope)
+    "/foo"
+  end
+end
+```
+
+[after_sign_in_path_for]: https://github.com/heartcombo/devise/wiki/How-To:-Redirect-back-to-current-page-after-sign-in,-sign-out,-sign-up,-update
+
+If you need to have different paths for multiple different types of resources,
+you can write something like this:
+
+```ruby
+class ApplicationController < ActionController::Base
+  def after_magic_link_sent_path_for(resource)
+    case resource.class
+    when FooUser
+      happy_path
+    when BarUser
+      sad_path
+    end
+  end
+end
+```
+
+And, if you need more complex behavior, you can always write a custom sessions
+controller for each resource:
+
+```ruby
+# app/controllers/custom_sessions_controller.rb
+class CustomSessionsController < Devise::Passwordless::SessionsController
+  def create
+    # your custom logic
+  end
+end
+
+# config/routes.rb
+Rails.application.routes.draw do
+  devise_for :users,
+    controllers: { sessions: "custom_sessions" }
+end
+```
+
+## Tokenizers
+
+Tokenizers handle encoding and decoding of magic link tokens. There are multiple
+pre-built ones to choose from, or [you can write your own](#your-own-custom-tokenizer).
+
+Set the default tokenizer in your Devise initializer (`config.passwordless_tokenizer`),
+which will be the global default. If you want a model to have a different tokenizer
+than the default, you can define a class method `::passwordless_tokenizer` on your
+model and that will be used instead. Models can have different tokenizers from
+each other in this way.
+
+### SignedGlobalIDTokenizer
+
+```ruby
+config.passwordless_tokenizer = "SignedGlobalIDTokenizer"
+```
+
+Tokens are [Rails signed Global IDs][globalid]. This is the default for new installs.
+
+Reasons to use or not use:
+
+* The implementation is short and simple, so less likely to be buggy
+* Should work with all ORMs that implement GlobalID support
+* Cannot add arbitrary metadata to generated tokens
+* Tokens are signed, not encrypted, so some data will be visible when base64-decoded
+* Tokens tend to be a little longer (~30 chars IME) than MessageEncryptors'
+
+[globalid]: https://github.com/rails/globalid
+
+### MessageEncryptorTokenizer
+
+```ruby
+config.passwordless_tokenizer = "MessageEncryptorTokenizer"
+```
+
+Tokens are encrypted using Rails's [MessageEncryptor][].
+
+[MessageEncryptor]: https://api.rubyonrails.org/classes/ActiveSupport/MessageEncryptor.html
+
+Reasons to use or not use:
+
+* This was the only tokenizer in previous library versions
+* The implementation is longer and more involved than SignedGlobalID
+* Written with ActiveRecord in mind but may work with other ORMs
+* Can add arbitrary extra metadata to tokens
+* Tokens are opaque, due to being encrypted - no data visible when base64-decoded
+* Tokens tend to be a little shorter than SignedGlobalID IME
+
+### Your own custom tokenizer
+
+It's straightforward to write your own tokenizer class; it just needs to respond to
+`::encode` and `::decode`:
+
+```ruby
+class LuckyUserTokenizer
+  def self.encode(resource, *args)
+    "8" * 88 # our token is always lucky!
+  end
+
+  def self.decode(token, resource_class, *args)
+    # ignore token and retrieve a random user
+    [resource_class.order("RANDOM()").limit(1).first, extra_data={}]
+  end
+end
+
+# config/initializers/devise.rb
+config.passwordless_tokenizer = "::LuckyUserTokenizer"
+```
+
+## Multiple user (resource) types
 
 Devise supports multiple resource types, so we do too.
 
@@ -157,18 +356,8 @@ Then just set up your routes like this:
 Rails.application.routes.draw do
   devise_for :users,
     controllers: { sessions: "devise/passwordless/sessions" }
-  devise_scope :user do
-    get "/users/magic_link",
-      to: "devise/passwordless/magic_links#show",
-      as: "users_magic_link"
-  end
   devise_for :admins,
     controllers: { sessions: "devise/passwordless/sessions" }
-  devise_scope :admin do
-    get "/admins/magic_link",
-      to: "devise/passwordless/magic_links#show",
-      as: "admins_magic_link"
-  end
 end
 ```
 
@@ -183,9 +372,11 @@ en:
       user:
         not_found_in_database: "Could not find a USER for that email address"
         magic_link_sent: "A USER login link has been sent to your email address. Please follow the link to log in to your account."
+        magic_link_sent_paranoid: "If your USER account exists, you will receive an email with a login link. Please follow the link to log in to your account."
       admin:
         not_found_in_database: "Could not find an ADMIN for that email address"
         magic_link_sent: "An ADMIN login link has been sent to your email address. Please follow the link to log in to your account."
+        magic_link_sent_paranoid: "If your ADMIN account exists, you will receive an email with a login link. Please follow the link to log in to your account."
     failure:
       user:
         magic_link_invalid: "Invalid or expired USER login link."
@@ -197,7 +388,7 @@ en:
         admin_subject: "Here's your ADMIN magic login link ✨"
 ```
 
-#### Scoped views
+### Scoped views
 
 If you have multiple Devise models, some that are passwordless and some that aren't, you will probably want to enable [Devise's `scoped_views` setting](https://henrytabima.github.io/rails-setup/docs/devise/configuring-views) so that the models have different signup and login pages (since some models will need password fields and others won't).
 
@@ -215,7 +406,123 @@ app/views/users/
 app/views/admins/
 ```
 
-### Notes on other Devise strategies
+## Combining password and passwordless auth in the same model
+
+It is possible to use both traditional password authentication (i.e. the
+`:database_authenticatable` strategy) alongside magic link authentication in
+the same model:
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  devise :database_authenticatable, :magic_link_authenticatable, :registerable,
+         :recoverable, :rememberable, :validatable
+end
+```
+
+How you end up implementing it will be highly dependent on your use case. By
+default, all password validations will still run - so on registration, users
+will have to provide passwords - but they'll be able to log in via either
+password OR magic link (you'll have to customize your routes and views to
+make the separate paths accessible).
+
+Here's an example routes file of that scenario (a separate namespace is
+needed because the password vs. passwordless paths use different sessions
+controllers):
+
+```ruby
+devise_for :users
+namespace "passwordless" do
+  devise_for :users,
+    controllers: { sessions: "devise/passwordless/sessions" }
+end
+```
+
+Visiting `/users/sign_in` will lead to a password sign in, while
+`/passwordless/users/sign_in` will lead to the magic link sign in flow
+(you'll need to [generate the necessary Devise views](#scoped-views)
+to support the different sign-in forms).
+
+### Disabling password authentication or magic link authentication
+
+Rather than *all* your users having access to *both* authentication methods,
+it may be the case that you want *some* users to use magic links, *some*
+to use passwords, or some combination between the two.
+
+This can be managed by defining some methods that disable the relevant
+authentication strategy and determine the failure message. Here are
+examples for both:
+
+### Disabling password authentication
+
+Let's say you want to disable password authentication for everyone except
+people named Bob:
+
+```ruby
+class User < ApplicationRecord
+  # devise :database_authenticatable, :magic_link_authenticatable, ...
+
+  def first_name_bob?
+    self.first_name.downcase == "bob"
+  end
+
+  # The `super` is important in the following two methods as other
+  # auth strategies chain onto these methods:
+
+  def active_for_authentication?
+    super && first_name_bob?
+  end
+
+  def inactive_message
+    first_name_bob? ? super : :first_name_not_bob
+  end
+end
+```
+
+Then, you add this to your `devise.yml` to customize the error message:
+
+```yaml
+devise:
+  failure:
+    first_name_not_bob: "Sorry, only Bobs may log in using their password. Try magic link login instead."
+```
+
+Now, when users not named Bob try to log in with their password, it'll fail with
+your custom failure message.
+
+### Disabling passwordless / magic link authentication
+
+Disabling magic link authentication is a similar process, just with different
+method names:
+
+```ruby
+class User < ApplicationRecord
+  # devise :database_authenticatable, :magic_link_authenticatable, ...
+
+  def first_name_alice?
+    self.first_name.downcase == "alice"
+  end
+
+  # The `super` is actually not important at the moment for these, but if
+  # any future Devise strategies were to extend this one, they will be.
+
+  def active_for_magic_link_authentication?
+    super && first_name_alice?
+  end
+
+  def magic_link_inactive_message
+    first_name_alice? ? super : :first_name_not_alice_magic_link
+  end
+end
+```
+
+```yaml
+devise:
+  failure:
+    first_name_not_alice_magic_link: "Sorry, only Alices may log in using magic links. Try password login instead."
+```
+
+## Compatibility with 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 that strategy assumes you're using a password auth strategy and relies on comparing the password's salt to validate cookies:
 
@@ -227,6 +534,54 @@ end
 
 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.
 
+## Hotwire/Turbo support
+
+If you're using Hotwire/Turbo, be sure that you're on Devise >= 4.9 and that you're
+setting the `config.responder` config value in your Devise initializer to appropriate
+values.
+
+See the [Devise 4.9 Turbo upgrade guide][] for more info.
+
+[Devise 4.9 Turbo upgrade guide]: https://github.com/heartcombo/devise/wiki/How-To:-Upgrade-to-Devise-4.9.0-%5BHotwire-Turbo-integration%5D
+
+## ActiveJob support
+
+If you want to use ActiveJob to send magic link emails asynchronously through
+a queuing backend, you can accomplish it the same way you
+[enable this functionality in any Devise install][devise-activejob]:
+
+```ruby
+class User
+  def send_devise_notification(notification, *args)
+    devise_mailer.send(notification, self, *args).deliver_later
+  end
+end
+```
+
+[devise-activejob]: https://github.com/heartcombo/devise/blob/main/README.md#activejob-integration
+
+## Rails logs security
+
+Rails's default configuration filters `:token` parameters out of request logs (and
+`Devise::Passwordless` will issue a warning if it detects the configuration doesn't). So request
+logs shouldn't link magic link tokens.
+
+However, there are some other default Rails logging behaviors that may cause plaintext magic
+link tokens to leak into log files:
+
+1. Action Mailer logs the entire contents of all outgoing emails to the DEBUG level. Magic link tokens delivered to users in email will be leaked.
+2. Active Job logs all arguments to every enqueued job at the INFO level. If you configure Devise to use `deliver_later` to send passwordless emails, magic link tokens will be leaked.
+
+Rails sets the production logger level to INFO by default. Consider changing your production logger level to WARN if you wish to prevent tokens from being leaked into your logs. In `config/environments/production.rb`:
+
+```ruby
+config.log_level = :warn
+```
+
+(Partially adapted from the [Devise guide on password reset tokens][], which this section also applies to)
+
+[Devise guide on password reset tokens]: https://github.com/heartcombo/devise/blob/main/README.md#password-reset-tokens-and-rails-logs
+
 ## Alternatives
 
 Other Ruby libraries that offer passwordless authentication: