passwordless 0.12.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b90e8f97825d92f0728154737c428d39cfecbedc9e02bbe6948d0861dd5e9c39
-  data.tar.gz: 2a5b288bf8c16004c6ec8fe7b8937e9f72496475e6e9af4e6a70c32a7a1d05dc
+  metadata.gz: 24d02d4dc7676adee968e3f922097f744ee41c2a1826d7622ffac01f3aaf76b8
+  data.tar.gz: 03624c6400113e2071eb038cd9406102870b3a56e1f8fa790bb9c190f17b95d5
 SHA512:
-  metadata.gz: 2350958cc2cb4628a6242a6c86ef08b3962fef2ba12fd9ed5a1bf8727f9254fc61fb77e9fa946bb015ebfc98eb81563d1e56aeb1c40d1cbc2ef96e66af512de9
-  data.tar.gz: 5fed7a3d7541a302fa9d6fc802bd530002846ea8cc4dae2057d03fdd799d66263752c766578bd96a441ab584d539739fbe55a63f7e258c5a7e1b16fdecb9eb7a
+  metadata.gz: 34e67e3b5a2be5cc657ee7193fa0ea76fc27ae7aad32413c66c4534bd2ce91540d7fe3ccdb2a2816a9d46053fd06d2f9c840d69e14cb7e5c49a45b3933be418e
+  data.tar.gz: ed550ba88a988109ad8192120fa25225c2c2fc161caff9beb9f51f5bd54baf72325c5baf02fb42da72a2a23ccb923687959aea517c2ce00879f580f82ab24559

data/README.md

@@ -10,42 +10,19 @@ Add authentication to your Rails app without all the icky-ness of passwords.
 
 ---
 
-## Table of Contents
-
-* [Installation](#installation)
-* [Usage](#usage)
-  * [Getting the current user, restricting access, the usual](#getting-the-current-user-restricting-access-the-usual)
-  * [Providing your own templates](#providing-your-own-templates)
-  * [Registering new users](#registering-new-users)
-  * [URLs and links](#urls-and-links)
-  * [Customize the way to send magic link](#customize-the-way-to-send-magic-link)
-  * [Generate your own magic links](#generate-your-own-magic-links)
-  * [Overrides](#overrides)
-* [Configuration](#configuration)
-  * [Customising token generation](#generating-tokens)
-  * [Token and Session Expiry](#token-and-session-expiry)
-  * [Redirecting back after sign-in](#redirecting-back-after-sign-in)
-  * [Claiming tokens](#claiming-tokens)
-  * [Supporting UUID primary keys](#supporting-uuid-primary-keys)
-* [Testing helpers](#testing-helpers)
-* [E-mail security](#e-mail-security)
-* [License](#license)
-
 ## Installation
 
-Add the `passwordless` gem to your `Gemfile`:
-
-```ruby
-gem 'passwordless'
-```
-
-Install it and copy over the migrations:
+Add to your bundle and copy over the migrations:
 
 ```sh
-$ bundle
+$ bundle add passwordless
 $ bin/rails passwordless:install:migrations
 ```
 
+### Upgrading
+
+See [Upgrading to Passwordless 1.0](docs/upgrading_to_1_0.md) for more details.
+
 ## Usage
 
 Passwordless creates a single model called `Passwordless::Session`. It doesn't come with its own `User` model, it expects you to create one:
@@ -97,6 +74,7 @@ class ApplicationController < ActionController::Base
 
   def require_user!
     return if current_user
+    save_passwordless_redirect_location!(User) # <-- optional, see below
     redirect_to root_path, flash: { error: 'You are not worthy!' }
   end
 end
@@ -116,30 +94,19 @@ end
 
 ### Providing your own templates
 
-Override `passwordless`' bundled views by adding your own. You can manually copy the specific views that you need or copy them to your application with `rails generate passwordless:views`.
+To make Passwordless look like your app, override the bundled views by adding your own. You can manually copy the specific views that you need or copy them to your application with `rails generate passwordless:views`.
 
-`passwordless` has 2 action views and 1 mailer view:
+Passwordless has 2 action views and 1 mailer view:
 
 ```sh
 # the form where the user inputs their email address
 app/views/passwordless/sessions/new.html.erb
-# shown after a user requests a magic link
-app/views/passwordless/sessions/create.html.erb
-# the mail with the magic link that gets sent
-app/views/passwordless/mailer/magic_link.text.erb
-```
-
-If you'd like to let the user know whether or not a record was found, `@resource` is provided to the view. You may override `app/views/passwordless/session/create.html.erb` for example like so:
-```erb
-<% if @resource.present? %>
-  <p>User found, check your inbox</p>
-<% else %>
-  <p>No user found with the provided email address</p>
-<% end %>
+# the form where the user inputs their just received token
+app/views/passwordless/sessions/show.html.erb
+# the email with the token and magic link
+app/views/passwordless/mailer/sign_in.text.erb
 ```
 
-Please note that, from a security standpoint, this is a **bad practice** because you'd be giving information about which users are registered on your system. It is recommended to use a single message similar to the default one: "If we found you in the system, we've sent you an email". The **best practice** is to never expose which emails are registered on your system.
-
 See [the bundled views](https://github.com/mikker/passwordless/tree/master/app/views/passwordless).
 
 ### Registering new users
@@ -152,13 +119,13 @@ class UsersController < ApplicationController
   # (unless you already have it in your ApplicationController)
 
   def create
-    @user = User.new user_params
+    @user = User.new(user_params)
 
     if @user.save
-      sign_in @user # <-- This!
-      redirect_to @user, flash: { notice: 'Welcome!' }
+      sign_in(build_passwordless_session(@user)) # <-- This!
+      redirect_to(@user, flash: { notice: 'Welcome!' })
     else
-      render :new
+      render(:new)
     end
   end
 
@@ -172,137 +139,90 @@ By default, Passwordless uses the resource name given to `passwordless_for` to g
 
 ```ruby
 passwordless_for :users
-  # <%= users.sign_in_path %> # => /users/sign_in
+  # <%= users_sign_in_path %> # => /users/sign_in
 
 passwordless_for :users, at: '/', as: :auth
-  # <%= auth.sign_in_path %> # => /sign_in
+  # <%= auth_sign_in_path %> # => /sign_in
 ```
 
-Also be sure to [specify ActionMailer's `default_url_options.host`](http://guides.rubyonrails.org/action_mailer_basics.html#generating-urls-in-action-mailer-views).
+Also be sure to
+[specify ActionMailer's `default_url_options.host`](http://guides.rubyonrails.org/action_mailer_basics.html#generating-urls-in-action-mailer-views).
 
-### Customize the way to send magic link
+## Configuration
 
-By default, magic link will send by email. You can customize this method. For example, you can send magic link via SMS.
+To customize Passwordless, create a file `config/initializers/passwordless.rb`.
 
-config/initializers/passwordless.rb
+The default values are shown below. It's recommended to only include the ones that you specifically want to modify.
 
 ```ruby
-Passwordless.after_session_save = lambda do |session, request|
-  # Default behavior is
-  # Passwordless::Mailer.magic_link(session).deliver_now
-
-  # You can change behavior to do something with session model. For example,
-  # session.authenticatable.send_sms
+Passwordless.configure do |config|
+  config.default_from_address = "CHANGE_ME@example.com"
+  config.parent_mailer = "ActionMailer::Base"
+  config.restrict_token_reuse = false # Can a token/link be used multiple times?
+  config.token_generator = Passwordless::ShortTokenGenerator.new # Used to generate magic link tokens.
+
+  config.expires_at = lambda { 1.year.from_now } # How long until a signed in session expires.
+  config.timeout_at = lambda { 10.minutes.from_now } # How long until a token/magic link times out.
+
+  config.redirect_back_after_sign_in = true # When enabled the user will be redirected to their previous page, or a page specified by the `destination_path` query parameter, if available.
+  config.redirect_to_response_options = {} # Additional options for redirects.
+  config.success_redirect_path = '/' # After a user successfully signs in
+  config.failure_redirect_path = '/' # After a sign in fails
+  config.sign_out_redirect_path = '/' # After a user signs out
 end
 ```
 
-You can access user model through authenticatable.
+### Delivery method
 
-### Generate your own magic links
+By default, Passwordless sends emails. See [Providing your own templates](#providing-your-own-templates). If you need to customize this further, you can do so in the `after_session_save` callback.
 
-Currently there is not an officially supported way to generate your own magic links to send in your own mailers.
-
-However, you can accomplish this with the following snippet of code.
+In `config/initializers/passwordless.rb`:
 
 ```ruby
-session = Passwordless::Session.new({
-  authenticatable: @manager,
-  user_agent: 'Command Line',
-  remote_addr: 'unknown',
-})
-session.save!
-@magic_link = send(Passwordless.mounted_as).token_sign_in_url(session.token)
-```
+Passwordless.configure do |config|
+  config.after_session_save = lambda do |session, request|
+    # Default behavior is
+    # Passwordless::Mailer.sign_in(session).deliver_now
 
-You can further customize this URL by specifying the destination path to be redirected to after the user has logged in. You can do this by adding the `destination_path` query parameter to the end of the URL. For example
-```
-@magic_link = "#{@magic_link}?destination_path=/your-custom-path"
-```
-
-### Overrides
-
-By default `passwordless` uses the `passwordless_with` column to _case insensitively_ fetch the resource.
-
-You can override this and provide your own customer fetcher by defining a class method `fetch_resource_for_passwordless` in your passwordless model. The method will be called with the downcased email and should return an `ActiveRecord` instance of the model.
-
-Example time:
-
-Let's say we would like to fetch the record and if it doesn't exist, create automatically.
-
-```ruby
-class User < ApplicationRecord
-  def self.fetch_resource_for_passwordless(email)
-    find_or_create_by(email: email)
+    # You can change behavior to do something with session model. For example,
+    # SmsApi.send_sms(session.authenticatable.phone_number, session.token)
   end
 end
 ```
 
-## Configuration
-
-The following configuration parameters are supported. You can override these for example in `initializers/passwordless.rb`.
+### Token generation
 
-The default values are shown below. It's recommended to only include the ones that you specifically want to override.
+By default Passwordless generates short, 6-digit, alpha numeric tokens. You can change the generator using `Passwordless.config.token_generator` to something else that responds to `call(session)` eg.:
 
 ```ruby
-Passwordless.default_from_address = "CHANGE_ME@example.com"
-Passwordless.parent_mailer = "ActionMailer::Base"
-Passwordless.token_generator = Passwordless::UrlSafeBase64Generator.new # Used to generate magic link tokens.
-Passwordless.restrict_token_reuse = false # By default a magic link token can be used multiple times.
-Passwordless.redirect_back_after_sign_in = true # When enabled the user will be redirected to their previous page, or a page specified by the `destination_path` query parameter, if available.
-
-Passwordless.expires_at = lambda { 1.year.from_now } # How long until a passwordless session expires.
-Passwordless.timeout_at = lambda { 1.hour.from_now } # How long until a magic link expires.
-
-# redirection session behavior
-Passwordless.redirect_to_response_options = {} # any allowed response_options for redirect_to can go in here
-
-# Default redirection paths
-Passwordless.success_redirect_path = '/' # When a user succeeds in logging in.
-Passwordless.failure_redirect_path = '/' # When a a login is failed for any reason.
-Passwordless.sign_out_redirect_path = '/' # When a user logs out.
-```
-
-### Customizing token generation
-
-By default Passwordless generates tokens using `SecureRandom.urlsafe_base64` but you can change that by setting `Passwordless.token_generator` to something else that responds to `call(session)` eg.:
-
-```ruby
-Passwordless.token_generator = -> (session) {
-  "probably-stupid-token-#{session.user_agent}-#{Time.current}"
-}
+Passwordless.configure do |config|
+  config.token_generator = lambda do |session|
+    "probably-stupid-token-#{session.user_agent}-#{Time.current}"
+  end
+end
 ```
 
-Session is going to keep generating tokens until it finds one that hasn't been used yet. So be sure to use some kind of method where matches are unlikely.
+Passwordless will keep generating tokens until it finds one that hasn't been used yet. So be sure to use some kind of method where matches are unlikely.
 
-### Token and Session Expiry
+### Timeout and Expiry
 
-Token timeout is the time by which the sign in token is invalidated. Post the timeout, the token cannot be used to sign-in to the app and the user would need to request it again.
+The _timeout_ is the time by which the generated token and magic link is invalidated. After this the token cannot be used to sign in to your app and the user will need to request a new token.
 
-Session expiry is the expiration time of the session of a logged in user. Once this is expired, user would need to log back in to create a new session.
+The _expiry_ is the expiration time of the session of a logged in user. Once this is expired, the user is signed out.
 
-#### Token timeout
+**Note:** Passwordless' session relies on Rails' own session and so will never live longer than that.
 
-By default, sign in tokens generated by Passwordless are made invalid after `1.hour` from the time they are generated. If you wish you can override this and supply your custom Proc function that will return a valid datetime object. Make sure the generated time is in the future.
-
-> Make sure to use a `.call`able object, like a proc or lambda as it will be called everytime a session is created.
+To configure your Rails session, in `config/initializers/session_store.rb`:
 
 ```ruby
-Passwordless.timeout_at = lambda { 2.hours.from_now }
-```
-
-#### Session Expiry
-
-Session expiry is the time when the actual session is itself expired, i.e. users will be logged out and has to sign back in post this expiry time. By default, sessions are valid for `1.year` from the time they are generated. You can override by providing your custom Proc function that returns a datetime object.
-
-> Make sure to use a `.call`able object, like a proc or lambda as it will be called everytime a session is created.
-
-```ruby
-Passwordless.expires_at = lambda { 24.hours.from_now }
+Rails.application.config.session_store :cookie_store,
+  expire_after: 1.year,
+  # ...
 ```
 
-### Redirecting back after sign-in
+### Redirection after sign-in
 
-By default Passwordless will redirect back to where the user wanted to go **if** it knows where that is, so you'll have to help it. `Passwordless::ControllerHelpers` provide a method for this:
+By default Passwordless will redirect back to where the user wanted to go _if_ it knows where that is -- so you'll have to help it. `Passwordless::ControllerHelpers` provide a method:
 
 ```ruby
 class ApplicationController < ActionController::Base
@@ -312,71 +232,45 @@ class ApplicationController < ActionController::Base
 
   def require_user!
     return if current_user
-    save_passwordless_redirect_location!(User) # <-- here we go!
+    save_passwordless_redirect_location!(User) # <-- this one!
     redirect_to root_path, flash: {error: 'You are not worthy!'}
   end
 end
 ```
 
-This can be turned off with `Passwordless.redirect_back_after_sign_in = false` but if you just don't save the previous destination, you'll be fine.
-
-### Claiming tokens
-
-Opt-in for marking tokens as `claimed` so they can only be used once.
-
-config/initializers/passwordless.rb
-
-```ruby
-# Default is `false`
-Passwordless.restrict_token_reuse = true
-```
-
-#### Upgrading an existing Rails app to use claim token
+This can also be turned off with `Passwordless.config.redirect_back_after_sign_in = false`.
 
-The simplest way to update your sessions table is with a single migration:
+### Looking up the user
 
-<details>
-<summary>Example migration</summary>
+By default Passwordless uses the `passwordless_with` column to _case insensitively_ fetch the user resource.
 
-```bash
-bin/rails generate migration add_claimed_at_to_passwordless_sessions
-```
+You can override this by defining a class method `fetch_resource_for_passwordless` in your user model. This method will be called with the down-cased, stripped `email` and should return an `ActiveRecord` instance.
 
 ```ruby
-class AddClaimedAtToPasswordlessSessions < ActiveRecord::Migration[5.2]
-  def change
-    add_column :passwordless_sessions, :claimed_at, :datetime
+class User < ApplicationRecord
+  def self.fetch_resource_for_passwordless(email)
+    find_or_create_by(email: email)
   end
 end
-
 ```
-</details>
 
-### Supporting UUID primary keys
+### Claiming tokens
+
+By default, a token/magic link **can** be used more than once.
 
-If your `users` table uses UUIDs for its primary keys, you will need to add a migration
-to change the type of `passwordless`' `authenticatable_id` field to match your primary key type (this will also involve dropping and recreating associated indices).
+To change, in `config/initializers/passwordless.rb`:
 
-Here is an example migration you can use:
 ```ruby
-class SupportUuidInPasswordlessSessions < ActiveRecord::Migration[6.0]
-  def change
-    remove_index :passwordless_sessions, column: [:authenticatable_type, :authenticatable_id] if index_exists? :authenticatable_type, :authenticatable_id
-    remove_column :passwordless_sessions, :authenticatable_id
-    add_column :passwordless_sessions, :authenticatable_id, :uuid
-    add_index :passwordless_sessions, [:authenticatable_type, :authenticatable_id], name: 'authenticatable'
-  end
+Passwordless.configure do |config|
+  config.restrict_token_reuse = true
 end
 ```
 
-Alternatively, you can use `add_reference` with `type: :uuid` in your migration (see docs [here](https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-add_reference)).
-
-## Testing helpers
+## Test helpers
 
 To help with testing, a set of test helpers are provided.
 
-If you are using RSpec, add the following line to your `spec/rails_helper.rb` or
-`spec/spec_helper.rb` if `rails_helper.rb` does not exist:
+If you are using RSpec, add the following line to your `spec/rails_helper.rb`:
 
 ```ruby
 require "passwordless/test_helpers"
@@ -388,7 +282,6 @@ If you are using TestUnit, add this line to your `test/test_helper.rb`:
 require "passwordless/test_helpers"
 ```
 
-
 Then in your controller, request, and system tests/specs, you can utilize the following methods:
 
 ```ruby
@@ -396,18 +289,18 @@ passwordless_sign_in(user) # signs you in as a user
 passwordless_sign_out # signs out user
 ```
 
-## E-mail security
+## Security considerations
 
-There's no reason that this approach should be less secure than the usual username/password combo. In fact this is most often a more secure option, as users don't get to choose the weak passwords they still use. In a way this is just the same as having each user go through "Forgot password" on every login.
+There's no reason that this approach should be less secure than the usual username/password combo. In fact this is most often a more secure option, as users don't get to choose the horrible passwords they can't seem to stop using. In a way, this is just the same as having each user go through "Forgot password" on every login.
 
-But be aware that when everyone authenticates via emails you send, the way you send those mails becomes a weak spot. Email services usually provide a log of all the mails you send so if your app's account is compromised, every user in the system is as well. (This is the same for "Forgot password".) [Reddit was compromised](https://thenextweb.com/hardfork/2018/01/05/reddit-bitcoin-cash-stolen-hack/) using this method.
+But be aware that when everyone authenticates via emails, the way you send those mails becomes a weak spot. Email services usually provide a log of all the mails you send so if your email delivery provider account is compromised, every user in the system is as well. (This is the same for "Forgot password".) [Reddit was once compromised](https://thenextweb.com/hardfork/2018/01/05/reddit-bitcoin-cash-stolen-hack/) using this method.
 
-Ideally you should set up your email provider to not log these mails. And be sure to turn on 2-factor auth if your provider supports it.
+Ideally you should set up your email provider to not log these mails. And be sure to turn on non-SMS 2-factor authentication if your provider supports it.
 
-# Alternatives
+## Alternatives
 
 - [OTP JWT](https://github.com/stas/otp-jwt) -- Passwordless JSON Web Tokens
 
-# License
+## License
 
 MIT

data/Rakefile

@@ -2,17 +2,19 @@
 
 begin
   require "bundler/setup"
+
 rescue LoadError
-  puts "You must `gem install bundler` and `bundle install` to run rake tasks"
+  puts("You must `gem install bundler` and `bundle install` to run rake tasks")
 end
 
 require "yard"
+
 YARD::Rake::YardocTask.new
-task docs: :yard
+task(docs: :yard)
 
 APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
-load "rails/tasks/engine.rake"
-load "rails/tasks/statistics.rake"
+load("rails/tasks/engine.rake")
+load("rails/tasks/statistics.rake")
 
 require "bundler/gem_tasks"
 
@@ -24,6 +26,4 @@ Rake::TestTask.new(:test) do |t|
   t.verbose = false
 end
 
-task default: :test
-
-require "standard/rake"
+task(default: :test)