rodauth-rails 0.5.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0d00b7ad2f6198fff3a5cc3c720c6f30d9296898e3fd764ddf7408e36232a6d
-  data.tar.gz: 9ba008116fc5521c98ed62dda5b1f6b2eccd733d06ccb0a2c5b9b4db8df94539
+  metadata.gz: a3f1fd01ddd20052bd15e3c822ff44ca4a6f5d425dd18892ecffa34146364437
+  data.tar.gz: 8907b8616edf882d21ebff69b461cc12dae737f8ec34bdaf5c2d58ac5cc9b632
 SHA512:
-  metadata.gz: 848873e599cfb8dc8a5d274ac5fec5987cf4c895c77757a4b21529ddcd9a635ba8086c037f55c55ef097ae926549234e5abebb97a5300f0ead6118927d737d91
-  data.tar.gz: aa75fb48217e79c40000cf1f226f36a65fdffdcb764233572ae45341b7ab9dd2f1d8f8470e593d8260495962b1b5c352e62d0d5e71fed0cb96891da93a0f344c
+  metadata.gz: 917915fc72c29b668716d3234f2f85e8c92406ea14a63e82284750a5536ec016acb8714064888732eed9fb1443cb803c11e0764b23a76de9de64a9fda11d577f
+  data.tar.gz: f30214be433882a3be04fb988fcd1d4860c50c8cb8beced94f8b7529f45904c8a8c1eb12486e39f890ccce39f1321a02f1e92fce2cc07ca24f1a86509ddd4a59

data/CHANGELOG.md

@@ -1,3 +1,41 @@
+## 0.8.1 (2021-01-04)
+
+* Fix blank email body when `json: true` and `ActionController::API` descendant are used (@janko)
+
+* Make view and email rendering work when there are multiple configurations and one is `json: :only` (@janko)
+
+* Don't attempt to protect against forgery when `ActionController::API` descendant is used (@janko)
+
+* Mark content of rodauth built-in partials as HTML-safe (@janko)
+
+## 0.8.0 (2021-01-03)
+
+* Add `--api` option to `rodauth:install` generator for choosing JSON-only configuration (@janko)
+
+* Don't blow up when a Rodauth request is made using an unsupported HTTP verb (@janko)
+
+## 0.7.0 (2020-11-27)
+
+* Add `#rails_controller_eval` method for running code in context of a controller instance (@janko)
+
+* Detect `secret_key_base` from credentials and `$SECRET_KEY_BASE` environment variable (@janko)
+
+## 0.6.1 (2020-11-25)
+
+* Generate the Rodauth controller for API-only Rails apps as well (@janko)
+
+* Fix remember cookie deadline not extending in remember feature (@janko)
+
+## 0.6.0 (2020-11-22)
+
+* Add `Rodauth::Rails.rodauth` method for retrieving Rodauth instance outside of request context (@janko)
+
+* Add default Action Dispatch response headers in Rodauth responses (@janko)
+
+* Run controller rescue handlers around Rodauth actions (@janko)
+
+* Run controller action callbacks around Rodauth actions (@janko)
+
 ## 0.5.0 (2020-11-16)
 
 * Support more Active Record adapters in `rodauth:install` generator (@janko)

data/README.md

@@ -4,16 +4,57 @@ Provides Rails integration for the [Rodauth] authentication framework.
 
 ## Resources
 
+Useful links:
+
 * [Rodauth documentation](http://rodauth.jeremyevans.net/documentation.html)
-* [rodauth-rails wiki](https://github.com/janko/rodauth-rails/wiki)
 * [Rails demo](https://github.com/janko/rodauth-demo-rails)
 
+Articles:
+
+* [Rodauth: A Refreshing Authentication Solution for Ruby](https://janko.io/rodauth-a-refreshing-authentication-solution-for-ruby/)
+* [Adding Authentication in Rails with Rodauth](https://janko.io/adding-authentication-in-rails-with-rodauth/)
+* [Adding Multifactor Authentication in Rails with Rodauth](https://janko.io/adding-multifactor-authentication-in-rails-with-rodauth/)
+
+## Why Rodauth?
+
+There are already several popular authentication solutions for Rails (Devise,
+Sorcery, Clearance, Authlogic), so why would you choose Rodauth? Well, because
+it has many advantages over the mentioned alternatives:
+
+* multifactor authentication ([TOTP][otp], [SMS codes][sms_codes], [recovery codes][recovery_codes], [WebAuthn][webauthn])
+* standardized [JSON API support][jwt] (for every feature)
+* enterprise security features ([password complexity][password_complexity], [disallow password reuse][disallow_password_reuse], [password expiration][password_expiration], [session expiration][session_expiration], [single session][single_session], [account expiration][account_expiration])
+* [email authentication][email_auth] (aka "passwordless")
+* [audit logging][audit_logging] (for any action)
+* ability to protect password hashes even in case of SQL injection ([more details][password protection])
+* additional bruteforce protection for tokens ([more details][bruteforce tokens])
+* uniform configuration DSL (any setting can be static or dynamic)
+* consistent before/after hooks around everything
+* dedicated object encapsulating all authentication logic
+
+## Upgrading
+
+### Upgrading to 0.7.0
+
+Starting from version 0.7.0, rodauth-rails now correctly detects Rails
+application's `secret_key_base` when setting default `hmac_secret`, including
+when it's set via credentials or `$SECRET_KEY_BASE` environment variable. This
+means that your authentication will now be more secure by default, and Rodauth
+features that require `hmac_secret` should now work automatically as well.
+
+However, if you've already been using rodauth-rails in production, where the
+`secret_key_base` is set via credentials or environment variable and `hmac_secret`
+was not explicitly set, the fact that your authentication will now start using
+HMACs has backwards compatibility considerations. See the [Rodauth
+documentation][hmac] for instructions on how to safely transition, or just set
+`hmac_secret nil` in your Rodauth configuration.
+
 ## Installation
 
 Add the gem to your Gemfile:
 
 ```rb
-gem "rodauth-rails", "~> 0.4"
+gem "rodauth-rails", "~> 0.6"
 
 # gem "jwt",      require: false # for JWT feature
 # gem "rotp",     require: false # for OTP feature
@@ -25,10 +66,17 @@ Then run `bundle install`.
 
 Next, run the install generator:
 
-```
+```sh
 $ rails generate rodauth:install
 ```
 
+Or if you want Rodauth endpoints to be exposed via JSON API:
+
+```sh
+$ rails generate rodauth:install --api
+$ bundle add jwt
+```
+
 The generator will create the following files:
 
 * Rodauth migration at `db/migrate/*_create_rodauth.rb`
@@ -111,8 +159,9 @@ end
 
 ### Controller
 
-Your Rodauth app will by default use `RodauthController` for view rendering
-and CSRF protection.
+Your Rodauth app will by default use `RodauthController` for view rendering,
+CSRF protection, and running controller callbacks and rescue handlers around
+Rodauth actions.
 
 ```rb
 # app/controllers/rodauth_controller.rb
@@ -131,9 +180,11 @@ class Account < ApplicationRecord
 end
 ```
 
-## Getting started
+## Usage
+
+### Routes
 
-First, let's see what routes our Rodauth middleware will handle:
+We can see the list of routes our Rodauth middleware handles:
 
 ```sh
 $ rails rodauth:routes
@@ -155,54 +206,57 @@ Routes handled by RodauthApp:
   /close-account           rodauth.close_account_path
 ```
 
-We can use this information to add some basic authentication navigation links
-to our home page:
+Using this information, we could add some basic authentication links to our
+navigation header:
 
 ```erb
-<ul>
-  <% if rodauth.authenticated? %>
-    <li><%= link_to "Sign out", rodauth.logout_path, method: :post %></li>
-  <% else %>
-    <li><%= link_to "Sign in", rodauth.login_path %></li>
-    <li><%= link_to "Sign up", rodauth.create_account_path %></li>
-  <% end %>
-</ul>
+<% if rodauth.logged_in? %>
+  <%= link_to "Sign out", rodauth.logout_path, method: :post %>
+<% else %>
+  <%= link_to "Sign in", rodauth.login_path %>
+  <%= link_to "Sign up", rodauth.create_account_path %>
+<% end %>
 ```
 
-These links are fully functional, feel free to visit them and interact with the
+These routes are fully functional, feel free to visit them and interact with the
 pages. The templates that ship with Rodauth aim to provide a complete
 authentication experience, and the forms use [Bootstrap] markup.
 
-Let's also load the account record for authenticated requests and expose it via
-`#current_account`:
+### Current account
+
+To be able to fetch currently authenticated account, let's define a
+`#current_account` method that fetches the account id from session and
+retrieves the corresponding account record:
 
 ```rb
 # app/controllers/application_controller.rb
 class ApplicationController < ActionController::Base
-  before_action :load_account, if: -> { rodauth.authenticated? }
+  before_action :current_account, if: -> { rodauth.logged_in? }
 
   private
 
-  def load_account
-    @current_account = Account.find(rodauth.session_value)
+  def current_account
+    @current_account ||= Account.find(rodauth.session_value)
   rescue ActiveRecord::RecordNotFound
     rodauth.logout
     rodauth.login_required
   end
-
-  attr_reader   :current_account
   helper_method :current_account
 end
 ```
+
+This allows us to access the current account in controllers and views:
+
 ```erb
 <p>Authenticated as: <%= current_account.email %></p>
 ```
 
 ### Requiring authentication
 
-Next, we'll likely want to require authentication for certain sections/pages of
-our app. We can do this in our Rodauth app's routing block, which helps keep
-the authentication logic encapsulated:
+We'll likely want to require authentication for certain parts of our app,
+redirecting the user to the login page if they're not logged in. We can do this
+in our Rodauth app's routing block, which helps keep the authentication logic
+encapsulated:
 
 ```rb
 # app/lib/rodauth_app.rb
@@ -260,9 +314,9 @@ end
 
 ### Views
 
-The templates built into Rodauth are useful when getting started, but at some
-point we'll probably want more control over the markup. For that we can run the
-following command:
+The templates built into Rodauth are useful when getting started, but soon
+you'll want to start editing the markup. You can run the following command to
+copy Rodauth templates into your Rails app:
 
 ```sh
 $ rails generate rodauth:views
@@ -286,7 +340,7 @@ $ rails generate rodauth:views --all
 ```
 
 You can also tell the generator to create views into another directory (in this
-case make sure to rename the Rodauth controller accordingly).
+case make sure to rename the Rodauth controller accordingly):
 
 ```sh
 # generates views into app/views/authentication
@@ -351,7 +405,7 @@ $ rails generate rodauth:mailer
 ```
 
 This will create a `RodauthMailer` with the associated mailer views in
-`app/views/rodauth_mailer` directory.
+`app/views/rodauth_mailer` directory:
 
 ```rb
 # app/mailers/rodauth_mailer.rb
@@ -366,8 +420,8 @@ end
 ```
 
 You can then uncomment the lines in your Rodauth configuration to have it call
-your mailer. If you've enabled additional authentication features, make sure to
-override their `send_*_email` methods as well.
+your mailer. If you've enabled additional authentication features that send
+emails, make sure to override their `create_*_email` methods as well.
 
 ```rb
 # app/lib/rodauth_app.rb
@@ -375,43 +429,45 @@ class RodauthApp < Rodauth::Rails::App
   # ...
   configure do
     # ...
-    send_reset_password_email do
-      mailer_send(:reset_password, email_to, reset_password_email_link)
+    create_reset_password_email do
+      RodauthMailer.reset_password(email_to, reset_password_email_link)
     end
-    send_verify_account_email do
-      mailer_send(:verify_account, email_to, verify_account_email_link)
+    create_verify_account_email do
+      RodauthMailer.verify_account(email_to, verify_account_email_link)
     end
-    send_verify_login_change_email do |login|
-      mailer_send(:verify_login_change, login, verify_login_change_old_login, verify_login_change_new_login, verify_login_change_email_link)
+    create_verify_login_change_email do |login|
+      RodauthMailer.verify_login_change(login, verify_login_change_old_login, verify_login_change_new_login, verify_login_change_email_link)
     end
-    send_password_changed_email do
-      mailer_send(:password_changed, email_to)
+    create_password_changed_email do
+      RodauthMailer.password_changed(email_to)
     end
-    # send_email_auth_email do
-    #   mailer_send(:email_auth, email_to, email_auth_email_link)
+    # create_email_auth_email do
+    #   RodauthMailer.email_auth(email_to, email_auth_email_link)
     # end
-    # send_unlock_account_email do
-    #   mailer_send(:unlock_account, email_to, unlock_account_email_link)
+    # create_unlock_account_email do
+    #   RodauthMailer.unlock_account(email_to, unlock_account_email_link)
     # end
-    auth_class_eval do
+    send_email do |email|
       # queue email delivery on the mailer after the transaction commits
-      def mailer_send(type, *args)
-        db.after_commit do
-          RodauthMailer.public_send(type, *args).deliver_later
-        end
-      end
+      db.after_commit { email.deliver_later }
     end
     # ...
   end
 end
 ```
 
+This approach can be used even if you're using a 3rd-party service for
+transactional emails, where emails are sent via HTTP instead of SMTP. Whatever
+the `create_*_email` block returns will be passed to `send_email`, so you can
+be creative.
+
 ### Migrations
 
-The install generator will have created some default tables, but you can use
-the migration generator to create tables for any additional Rodauth features:
+The install generator will create a migration for tables used by the Rodauth
+features enabled by default. For any additional features, you can use the
+migration generator to create the corresponding tables:
 
-```
+```sh
 $ rails generate rodauth:migration otp sms_codes recovery_codes
 ```
 ```rb
@@ -425,36 +481,50 @@ class CreateRodauthOtpSmsCodesRecoveryCodes < ActiveRecord::Migration
 end
 ```
 
-### JSON API
+### Calling controller methods
 
-JSON API support in Rodauth is provided by the [JWT feature]. First you'll need
-to add the [JWT gem] to your Gemfile:
+When using Rodauth before/after hooks or generally overriding your Rodauth
+configuration, in some cases you might want to call methods defined on your
+controllers. You can do so with `rails_controller_eval`, for example:
 
 ```rb
-gem "jwt"
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  private
+  def setup_tracking(account_id)
+    # ... some implementation ...
+  end
+end
 ```
-
-The following configuration will enable the Rodauth endpoints to be accessed
-via JSON requests (in addition to HTML requests):
-
 ```rb
 # app/lib/rodauth_app.rb
 class RodauthApp < Rodauth::Rails::App
-  configure(json: true) do
-    # ...
-    enable :jwt
-    jwt_secret "...your secret key..."
-    # ...
+  configure do
+    after_create_account do
+      rails_controller_eval { setup_tracking(account_id) }
+    end
   end
 end
 ```
 
-If you want the endpoints to be only accessible via JSON requests, or if your
-Rails app is in API-only mode, instead of `json: true` pass `json: :only` to
-the configure method.
+### Rodauth instance
+
+In some cases you might need to use Rodauth more programmatically, and perform
+Rodauth operations outside of the request context. rodauth-rails gives you the
+ability to retrieve the Rodauth instance:
 
-Make sure to store the `jwt_secret` in a secure place, such as Rails
-credentials or environment variables.
+```rb
+rodauth = Rodauth::Rails.rodauth # or Rodauth::Rails.rodauth(:secondary)
+
+rodauth.login_url #=> "https://example.com/login"
+rodauth.account_from_login("user@example.com") # loads user by email
+rodauth.password_match?("secret") #=> true
+rodauth.setup_account_verification
+rodauth.close_account
+```
+
+This Rodauth instance will be initialized with basic Rack env that allows is it
+to generate URLs, using `config.action_mailer.default_url_options` options.
 
 ## How it works
 
@@ -500,19 +570,45 @@ end
 The `Rodauth::Rails::App` class is a [Roda] subclass that provides Rails
 integration for Rodauth:
 
-* uses Rails' flash instead of Roda's
-* uses Rails' CSRF protection instead of Roda's
+* uses Action Dispatch flash instead of Roda's
+* uses Action Dispatch CSRF protection instead of Roda's
 * sets [HMAC] secret to Rails' secret key base
-* uses ActionController for rendering templates
-* uses ActionMailer for sending emails
+* uses Action Controller for rendering templates
+* runs Action Controller callbacks & rescue handlers around Rodauth actions
+* uses Action Mailer for sending emails
 
-The `configure { ... }` method wraps configuring the Rodauth plugin, forwarding
+The `configure` method wraps configuring the Rodauth plugin, forwarding
 any additional [plugin options].
 
 ```rb
-configure { ... }             # defining default Rodauth configuration
-configure(json: true) { ... } # passing options to the Rodauth plugin
-configure(:secondary) { ... } # defining multiple Rodauth configurations
+class RodauthApp < Rodauth::Rails::App
+  configure { ... }             # defining default Rodauth configuration
+  configure(json: true) { ... } # passing options to the Rodauth plugin
+  configure(:secondary) { ... } # defining multiple Rodauth configurations
+end
+```
+
+The `route` block is provided by Roda, and it's called on each request before
+it reaches the Rails router.
+
+```rb
+class RodauthApp < Rodauth::Rails::App
+  route do |r|
+    # ... called before each request ...
+  end
+end
+```
+
+Since `Rodauth::Rails::App` is just a Roda subclass, you can do anything you
+would with a Roda app, such as loading additional Roda plugins:
+
+```rb
+class RodauthApp < Rodauth::Rails::App
+  plugin :request_headers # easier access to request headers
+  plugin :typecast_params # methods for conversion of request params
+  plugin :default_headers, { "Foo" => "Bar" }
+  # ...
+end
 ```
 
 ### Sequel
@@ -528,6 +624,142 @@ connection (using the [sequel-activerecord_connection] gem).
 This means that, from the usage perspective, Sequel can be considered just
 as an implementation detail of Rodauth.
 
+## JSON API
+
+JSON API support in Rodauth is provided by the [JWT feature][jwt]. You'll need
+to install the [JWT gem], enable JSON support and enable the JWT feature:
+
+```sh
+$ bundle add jwt
+```
+```rb
+# app/lib/rodauth_app.rb
+class RodauthApp < Rodauth::Rails::App
+  configure(json: :only) do
+    # ...
+    enable :jwt
+    # make sure to store the JWT secret below in a safe place
+    jwt_secret "...your secret key..."
+    # ...
+  end
+end
+```
+
+With the above configuration, Rodauth routes will only be accessible via JSON
+requests. If you still want to allow HTML access alongside JSON, change `json:
+:only` to `json: true`.
+
+Emails will automatically work in JSON-only mode, because `Rodauth::Rails::App`
+comes with Roda's `render` plugin loaded. They are customized the same as in
+the non-JSON case.
+
+## OmniAuth
+
+While Rodauth doesn't yet come with [OmniAuth] integration, we can build one
+ourselves using the existing Rodauth API.
+
+In order to allow the user to login via multiple external providers, let's
+create an `account_identities` table that will have a many-to-one relationship
+with the `accounts` table:
+
+```sh
+$ rails generate model AccountIdentity
+```
+```rb
+# db/migrate/*_create_account_identities.rb
+class CreateAccountIdentities < ActiveRecord::Migration
+  def change
+    create_table :account_identities do |t|
+      t.references :account, null: false, foreign_key: { on_delete: :cascade }
+      t.string :provider, null: false
+      t.string :uid, null: false
+      t.jsonb :info, null: false, default: {} # adjust JSON column type for your database
+
+      t.timestamps
+
+      t.index [:provider, :uid], unique: true
+    end
+  end
+end
+```
+```rb
+# app/models/account_identity.rb
+class AcccountIdentity < ApplicationRecord
+  belongs_to :account
+end
+```
+```rb
+# app/models/account.rb
+class Account < ApplicationRecord
+  has_many :identities, class_name: "AccountIdentity"
+end
+```
+
+Let's assume we want to implement Facebook login, and have added the
+corresponding OmniAuth strategy to the middleware stack, together with an
+authorization link on the login form:
+
+```rb
+Rails.application.config.middleware.use OmniAuth::Builder do
+  provider :facebook, ENV["FACEBOOK_APP_ID"], ENV["FACEBOOK_APP_SECRET"],
+    scope: "email", callback_path: "/auth/facebook/callback"
+end
+```
+```erb
+<%= link_to "Login via Facebook", "/auth/facebook" %>
+```
+
+Let's implement the OmniAuth callback endpoint on our Rodauth controller:
+
+```rb
+# config/routes.rb
+Rails.application.routes.draw do
+  # ...
+  get "/auth/:provider/callback", to: "rodauth#omniauth"
+end
+```
+```rb
+# app/controllres/rodauth_controller.rb
+class RodauthController < ApplicationController
+  def omniauth
+    auth = request.env["omniauth.auth"]
+
+    # attempt to find existing identity directly
+    identity = AccountIdentity.find_by(provider: auth["provider"], uid: auth["uid"])
+
+    if identity
+      # update any external info changes
+      identity.update!(info: auth["info"])
+      # set account from identity
+      account = identity.account
+    end
+
+    # attempt to find an existing account by email
+    account ||= Account.find_by(email: auth["info"]["email"])
+
+    # disallow login if account is not verified
+    if account && account.status != rodauth.account_open_status_value
+      redirect_to rodauth.login_path, alert: rodauth.unverified_account_message
+      return
+    end
+
+    # create new account if it doesn't exist
+    unless account
+      account = Account.create!(email: auth["info"]["email"])
+    end
+
+    # create new identity if it doesn't exist
+    unless identity
+      account.identities.create!(provider: auth["provider"], uid: auth["uid"], info: auth["info"])
+    end
+
+    # login with Rodauth
+    rodauth.account_from_login(account.email)
+    rodauth.login("omniauth")
+  end
+end
+```
+
 ## Configuring
 
 For the list of configuration methods provided by Rodauth, see the [feature
@@ -561,6 +793,37 @@ Rodauth::Rails.configure do |config|
 end
 ```
 
+## Custom extensions
+
+When developing custom extensions for Rodauth inside your Rails project, it's
+better to use plain modules (at least in the beginning), because Rodauth
+feature API doesn't yet support Zeitwerk reloading well.
+
+```rb
+# app/lib/rodauth_argon2.rb
+module RodauthArgon2
+  def password_hash(password)
+    Argon2::Password.create(password, t_cost: password_hash_cost, m_cost: password_hash_cost)
+  end
+
+  def password_hash_match?(hash, password)
+    Argon2::Password.verify_password(password, hash)
+  end
+end
+```
+```rb
+# app/lib/rodauth_app.rb
+class RodauthApp < Rodauth::Rails::App
+  configure do
+    # ...
+    auth_class_eval do
+      include RodauthArgon2
+    end
+    # ...
+  end
+end
+```
+
 ## Testing
 
 If you're writing system tests, it's generally better to go through the actual
@@ -633,17 +896,15 @@ Rodauth method for creating database functions:
 
 ```rb
 # db/migrate/*_create_rodauth_database_functions.rb
+require "rodauth/migrations"
+
 class CreateRodauthDatabaseFunctions < ActiveRecord::Migration
   def up
-    # ...
     Rodauth.create_database_authentication_functions(DB)
-    # ...
   end
 
   def down
-    # ...
     Rodauth.drop_database_authentication_functions(DB)
-    # ...
   end
 end
 ```
@@ -700,9 +961,7 @@ conduct](https://github.com/janko/rodauth-rails/blob/master/CODE_OF_CONDUCT.md).
 
 [Rodauth]: https://github.com/jeremyevans/rodauth
 [Sequel]: https://github.com/jeremyevans/sequel
-[rendering views outside of controllers]: https://blog.bigbinary.com/2016/01/08/rendering-views-outside-of-controllers-in-rails-5.html
 [feature documentation]: http://rodauth.jeremyevans.net/documentation.html
-[JWT feature]: http://rodauth.jeremyevans.net/rdoc/files/doc/jwt_rdoc.html
 [JWT gem]: https://github.com/jwt/ruby-jwt
 [Bootstrap]: https://getbootstrap.com/
 [Roda]: http://roda.jeremyevans.net/
@@ -711,3 +970,20 @@ conduct](https://github.com/janko/rodauth-rails/blob/master/CODE_OF_CONDUCT.md).
 [Rodauth migration]: http://rodauth.jeremyevans.net/rdoc/files/README_rdoc.html#label-Creating+tables
 [sequel-activerecord_connection]: https://github.com/janko/sequel-activerecord_connection
 [plugin options]: http://rodauth.jeremyevans.net/rdoc/files/README_rdoc.html#label-Plugin+Options
+[hmac]: http://rodauth.jeremyevans.net/rdoc/files/README_rdoc.html#label-HMAC
+[OmniAuth]: https://github.com/omniauth/omniauth
+[otp]: http://rodauth.jeremyevans.net/rdoc/files/doc/otp_rdoc.html
+[sms_codes]: http://rodauth.jeremyevans.net/rdoc/files/doc/sms_codes_rdoc.html
+[recovery_codes]: http://rodauth.jeremyevans.net/rdoc/files/doc/recovery_codes_rdoc.html
+[webauthn]: http://rodauth.jeremyevans.net/rdoc/files/doc/webauthn_rdoc.html
+[jwt]: http://rodauth.jeremyevans.net/rdoc/files/doc/jwt_rdoc.html
+[email_auth]: http://rodauth.jeremyevans.net/rdoc/files/doc/email_auth_rdoc.html
+[audit_logging]: http://rodauth.jeremyevans.net/rdoc/files/doc/audit_logging_rdoc.html
+[password protection]: https://github.com/jeremyevans/rodauth#label-Password+Hash+Access+Via+Database+Functions
+[bruteforce tokens]: https://github.com/jeremyevans/rodauth#label-Tokens
+[password_complexity]: http://rodauth.jeremyevans.net/rdoc/files/doc/password_complexity_rdoc.html
+[disallow_password_reuse]: http://rodauth.jeremyevans.net/rdoc/files/doc/disallow_password_reuse_rdoc.html
+[password_expiration]: http://rodauth.jeremyevans.net/rdoc/files/doc/password_expiration_rdoc.html
+[session_expiration]: http://rodauth.jeremyevans.net/rdoc/files/doc/session_expiration_rdoc.html
+[single_session]: http://rodauth.jeremyevans.net/rdoc/files/doc/single_session_rdoc.html
+[account_expiration]: http://rodauth.jeremyevans.net/rdoc/files/doc/account_expiration_rdoc.html

data/lib/generators/rodauth/install_generator.rb

@@ -13,6 +13,15 @@ module Rodauth
         source_root "#{__dir__}/templates"
         namespace "rodauth:install"
 
+        # The :api option is a Rails-recognized option that always
+        # defaults to false, so we make it use our provided default
+        # value instead.
+        def self.default_value_for_option(name, options)
+          name == :api ? options[:default] : super
+        end
+
+        class_option :api, type: :boolean, desc: "Generate JSON-only configuration"
+
         def create_rodauth_migration
           return unless defined?(ActiveRecord::Base)
 
@@ -35,8 +44,6 @@ module Rodauth
         end
 
         def create_rodauth_controller
-          return if api_only?
-
           template "app/controllers/rodauth_controller.rb"
         end
 
@@ -77,9 +84,11 @@ module Rodauth
         end
 
         def api_only?
-          return unless ::Rails.gem_version >= Gem::Version.new("5.0")
-
-          ::Rails.application.config.api_only
+          if options.key?(:api)
+            options[:api]
+          elsif ::Rails.gem_version >= Gem::Version.new("5.0")
+            ::Rails.application.config.api_only
+          end
         end
 
         def migration_features

data/lib/generators/rodauth/templates/app/controllers/rodauth_controller.rb

@@ -1,3 +1,4 @@
 class RodauthController < ApplicationController
-  # used by Rodauth for rendering views and CSRF protection
+  # used by Rodauth for rendering views, CSRF protection, and running any
+  # registered action callbacks and rescue_from handlers
 end

data/lib/generators/rodauth/templates/app/lib/rodauth_app.rb

@@ -15,11 +15,9 @@ class RodauthApp < Rodauth::Rails::App
     # Defaults to Rails `secret_key_base`, but you can use your own secret key.
     # hmac_secret "<%= SecureRandom.hex(64) %>"
 
-<% unless api_only? -%>
     # Specify the controller used for view rendering and CSRF verification.
     rails_controller { RodauthController }
 
-<% end -%>
     # Store account status in a text column.
     account_status_column :status
     account_unverified_status_value "unverified"
@@ -59,31 +57,27 @@ class RodauthApp < Rodauth::Rails::App
 
     # ==> Emails
     # Uncomment the lines below once you've imported mailer views.
-    # send_reset_password_email do
-    #   mailer_send(:reset_password, email_to, reset_password_email_link)
+    # create_reset_password_email do
+    #   RodauthMailer.reset_password(email_to, reset_password_email_link)
     # end
-    # send_verify_account_email do
-    #   mailer_send(:verify_account, email_to, verify_account_email_link)
+    # create_verify_account_email do
+    #   RodauthMailer.verify_account(email_to, verify_account_email_link)
     # end
-    # send_verify_login_change_email do |login|
-    #   mailer_send(:verify_login_change, login, verify_login_change_old_login, verify_login_change_new_login, verify_login_change_email_link)
+    # create_verify_login_change_email do |login|
+    #   RodauthMailer.verify_login_change(login, verify_login_change_old_login, verify_login_change_new_login, verify_login_change_email_link)
     # end
-    # send_password_changed_email do
-    #   mailer_send(:password_changed, email_to)
+    # create_password_changed_email do
+    #   RodauthMailer.password_changed(email_to)
     # end
-    # # send_email_auth_email do
-    # #   mailer_send(:email_auth, email_to, email_auth_email_link)
+    # # create_email_auth_email do
+    # #   RodauthMailer.email_auth(email_to, email_auth_email_link)
     # # end
-    # # send_unlock_account_email do
-    # #   mailer_send(:unlock_account, email_to, unlock_account_email_link)
+    # # create_unlock_account_email do
+    # #   RodauthMailer.unlock_account(email_to, unlock_account_email_link)
     # # end
-    # auth_class_eval do
+    # send_email do |email|
     #   # queue email delivery on the mailer after the transaction commits
-    #   def mailer_send(type, *args)
-    #     db.after_commit do
-    #       RodauthMailer.public_send(type, *args).deliver_later
-    #     end
-    #   end
+    #   db.after_commit { email.deliver_later }
     # end
 
     # In the meantime you can tweak settings for emails created by Rodauth

data/lib/rodauth/rails.rb

@@ -9,14 +9,43 @@ module Rodauth
     # This allows the developer to avoid loading Rodauth at boot time.
     autoload :App, "rodauth/rails/app"
 
-    def self.configure
-      yield self
-    end
-
     @app = nil
     @middleware = true
 
     class << self
+      def rodauth(name = nil)
+        url_options = ActionMailer::Base.default_url_options
+
+        scheme   = url_options[:protocol] || "http"
+        port     = url_options[:port]
+        port   ||= Rack::Request::DEFAULT_PORTS[scheme] if Gem::Version.new(Rack.release) < Gem::Version.new("2.0")
+        host     = url_options[:host]
+        host    += ":#{port}" if port
+
+        rack_env = {
+          "HTTP_HOST"       => host,
+          "rack.url_scheme" => scheme,
+        }
+
+        scope = app.new(rack_env)
+
+        scope.rodauth(name)
+      end
+
+      if ::Rails.gem_version >= Gem::Version.new("5.2")
+        def secret_key_base
+          ::Rails.application.secret_key_base
+        end
+      else
+        def secret_key_base
+          ::Rails.application.secrets.secret_key_base
+        end
+      end
+
+      def configure
+        yield self
+      end
+
       attr_writer :app
       attr_writer :middleware
 

data/lib/rodauth/rails/app.rb

@@ -1,10 +1,14 @@
 require "roda"
+require "rodauth"
+require "rodauth/rails/feature"
 
 module Rodauth
   module Rails
     # The superclass for creating a Rodauth middleware.
     class App < Roda
-      plugin :middleware
+      require "rodauth/rails/app/middleware"
+      plugin Middleware
+
       plugin :hooks
       plugin :render, layout: false
 
@@ -18,6 +22,12 @@ module Rodauth
           # load the Rails integration
           enable :rails
 
+          if options[:json] == :only && ActionPack.version >= Gem::Version.new("5.0")
+            rails_controller { ActionController::API }
+          else
+            rails_controller { ActionController::Base }
+          end
+
           # database functions are more complex to set up, so disable them by default
           use_database_authentication_functions? false
 
@@ -25,7 +35,7 @@ module Rodauth
           set_deadline_values? true
 
           # use HMACs for additional security
-          hmac_secret { ::Rails.application.secrets.secret_key_base }
+          hmac_secret { Rodauth::Rails.secret_key_base }
 
           # evaluate user configuration
           instance_exec(&block)

data/lib/rodauth/rails/app/flash.rb

@@ -1,7 +1,7 @@
 module Rodauth
   module Rails
     class App
-      # Sets up Rails' flash integration.
+      # Roda plugin that sets up Rails flash integration.
       module Flash
         def self.load_dependencies(app)
           app.plugin :hooks

data/lib/rodauth/rails/app/middleware.rb

@@ -0,0 +1,26 @@
+module Rodauth
+  module Rails
+    class App
+      # Roda plugin that extends middleware plugin by propagating response headers.
+      module Middleware
+        def self.load_dependencies(app)
+          app.plugin :hooks
+        end
+
+        def self.configure(app)
+          app.after do
+            if response.empty? && response.headers.any?
+              env["rodauth.rails.headers"] = response.headers
+            end
+          end
+
+          app.plugin :middleware, handle_result: -> (env, res) do
+            if headers = env.delete("rodauth.rails.headers")
+              res[1] = headers.merge(res[1])
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rodauth/rails/feature.rb

@@ -9,10 +9,11 @@ module Rodauth
       :rails_csrf_param,
       :rails_csrf_token,
       :rails_check_csrf!,
-      :rails_controller_instance,
       :rails_controller,
     )
 
+    auth_cached_method :rails_controller_instance
+
     # Renders templates with layout. First tries to render a user-defined
     # template, otherwise falls back to Rodauth's template.
     def view(page, *)
@@ -25,7 +26,12 @@ module Rodauth
     def render(page)
       rails_render(partial: page.tr("-", "_"), layout: false) ||
         rails_render(action: page.tr("-", "_"), layout: false) ||
-        super
+        super.html_safe
+    end
+
+    # Render Rails CSRF tags in Rodauth templates.
+    def csrf_tag(*)
+      rails_csrf_tag
     end
 
     # Verify Rails' authenticity token.
@@ -38,18 +44,77 @@ module Rodauth
       true
     end
 
-    # Render Rails CSRF tags in Rodauth templates.
-    def csrf_tag(*)
-      rails_csrf_tag
-    end
-
     # Default the flash error key to Rails' default :alert.
     def flash_error_key
       :alert
     end
 
+    # Evaluates the block in context of a Rodauth controller instance.
+    def rails_controller_eval(&block)
+      rails_controller_instance.instance_exec(&block)
+    end
+
+    def button(*)
+      super.html_safe
+    end
+
     private
 
+    # Runs controller callbacks and rescue handlers around Rodauth actions.
+    def _around_rodauth(&block)
+      result = nil
+
+      rails_controller_rescue do
+        rails_controller_callbacks do
+          result = catch(:halt) { super(&block) }
+        end
+      end
+
+      if rails_controller_instance.performed?
+        rails_controller_response
+      elsif result
+        result[1].merge!(rails_controller_instance.response.headers)
+        throw :halt, result
+      else
+        result
+      end
+    end
+
+    # Runs any #(before|around|after)_action controller callbacks.
+    def rails_controller_callbacks
+      # don't verify CSRF token as part of callbacks, Rodauth will do that
+      rails_controller_forgery_protection { false }
+
+      rails_controller_instance.run_callbacks(:process_action) do
+        # turn the setting back to default so that form tags generate CSRF tags
+        rails_controller_forgery_protection { rails_controller.allow_forgery_protection }
+
+        yield
+      end
+    end
+
+    # Runs any registered #rescue_from controller handlers.
+    def rails_controller_rescue
+      yield
+    rescue Exception => exception
+      rails_controller_instance.rescue_with_handler(exception) || raise
+
+      unless rails_controller_instance.performed?
+        raise Rodauth::Rails::Error, "rescue_from handler didn't write any response"
+      end
+    end
+
+    # Returns Roda response from controller response if set.
+    def rails_controller_response
+      controller_response = rails_controller_instance.response
+
+      response.status = controller_response.status
+      response.headers.merge! controller_response.headers
+      response.write controller_response.body
+
+      request.halt
+    end
+
     # Create emails with ActionMailer which uses configured delivery method.
     def create_email_to(to, subject, body)
       Mailer.create_email(to: to, from: email_from, subject: "#{email_subject_prefix}#{subject}", body: body)
@@ -62,13 +127,16 @@ module Rodauth
 
     # Calls the Rails renderer, returning nil if a template is missing.
     def rails_render(*args)
-      return if only_json?
+      return if rails_api_controller?
 
-      begin
-        rails_controller_instance.render_to_string(*args)
-      rescue ActionView::MissingTemplate
-        nil
-      end
+      rails_controller_instance.render_to_string(*args)
+    rescue ActionView::MissingTemplate
+      nil
+    end
+
+    # Calls the controller to verify the authenticity token.
+    def rails_check_csrf!
+      rails_controller_instance.send(:verify_authenticity_token)
     end
 
     # Hidden tag with Rails CSRF token inserted into Rodauth templates.
@@ -86,30 +154,37 @@ module Rodauth
       rails_controller_instance.send(:form_authenticity_token)
     end
 
-    # Calls the controller to verify the authenticity token.
-    def rails_check_csrf!
-      rails_controller_instance.send(:verify_authenticity_token)
+    # allows/disables forgery protection
+    def rails_controller_forgery_protection(&value)
+      return if rails_api_controller?
+
+      rails_controller_instance.allow_forgery_protection = value.call
     end
 
     # Instances of the configured controller with current request's env hash.
-    def rails_controller_instance
-      request  = ActionDispatch::Request.new(scope.env)
-      instance = rails_controller.new
+    def _rails_controller_instance
+      controller    = rails_controller.new
+      rails_request = ActionDispatch::Request.new(scope.env)
 
-      if ActionPack.version >= Gem::Version.new("5.0")
-        instance.set_request! request
-        instance.set_response! rails_controller.make_response!(request)
-      else
-        instance.send(:set_response!, request)
-        instance.instance_variable_set(:@_request, request)
-      end
+      prepare_rails_controller(controller, rails_request)
+
+      controller
+    end
 
-      instance
+    if ActionPack.version >= Gem::Version.new("5.0")
+      def prepare_rails_controller(controller, rails_request)
+        controller.set_request! rails_request
+        controller.set_response! rails_controller.make_response!(rails_request)
+      end
+    else
+      def prepare_rails_controller(controller, rails_request)
+        controller.send(:set_response!, rails_request)
+        controller.instance_variable_set(:@_request, rails_request)
+      end
     end
 
-    # Controller class to use for rendering and CSRF protection.
-    def rails_controller
-      ActionController::Base
+    def rails_api_controller?
+      defined?(ActionController::API) && rails_controller <= ActionController::API
     end
 
     # ActionMailer subclass for correct email delivering.

data/lib/rodauth/rails/tasks.rake

@@ -3,19 +3,16 @@ namespace :rodauth do
     app = Rodauth::Rails.app
 
     puts "Routes handled by #{app}:"
-    puts
 
-    app.opts[:rodauths].each do |rodauth_name, rodauth_class|
-      route_names = rodauth_class.routes
-        .map { |handle_method| handle_method.to_s.sub(/\Ahandle_/, "") }
-        .uniq
+    app.opts[:rodauths].each_key do |rodauth_name|
+      rodauth = Rodauth::Rails.rodauth(rodauth_name)
 
-      rodauth = rodauth_class.allocate
+      routes = rodauth.class.routes.map do |handle_method|
+        path_method = "#{handle_method.to_s.sub(/\Ahandle_/, "")}_path"
 
-      routes = route_names.map do |name|
         [
-          rodauth.public_send(:"#{name}_path"),
-          "rodauth#{rodauth_name && "(:#{rodauth_name})"}.#{name}_path",
+          rodauth.public_send(path_method),
+          "rodauth#{rodauth_name && "(:#{rodauth_name})"}.#{path_method}",
         ]
       end
 
@@ -25,8 +22,7 @@ namespace :rodauth do
         "#{path.ljust(padding)}  #{code}"
       end
 
-      puts "  #{route_lines.join("\n  ")}"
-      puts
+      puts "\n  #{route_lines.join("\n  ")}" unless route_lines.empty?
     end
   end
 end

data/lib/rodauth/rails/version.rb

@@ -1,5 +1,5 @@
 module Rodauth
   module Rails
-    VERSION = "0.5.0"
+    VERSION = "0.8.1"
   end
 end

data/rodauth-rails.gemspec

@@ -17,8 +17,10 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "railties", ">= 4.2", "< 7"
-  spec.add_dependency "rodauth", "~> 2.1"
+  spec.add_dependency "rodauth", "~> 2.7"
   spec.add_dependency "sequel-activerecord_connection", "~> 1.1"
   spec.add_dependency "tilt"
   spec.add_dependency "bcrypt"
+
+  spec.add_development_dependency "jwt"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rodauth-rails
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Janko Marohnić
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-11-16 00:00:00.000000000 Z
+date: 2021-01-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -36,14 +36,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '2.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '2.7'
 - !ruby/object:Gem::Dependency
   name: sequel-activerecord_connection
   requirement: !ruby/object:Gem::Requirement
@@ -86,6 +86,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  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: Provides Rails integration for Rodauth.
 email:
 - janko.marohnic@gmail.com
@@ -187,10 +201,10 @@ files:
 - lib/generators/rodauth/templates/db/migrate/create_rodauth.rb
 - lib/generators/rodauth/views_generator.rb
 - lib/rodauth-rails.rb
-- lib/rodauth/features/rails.rb
 - lib/rodauth/rails.rb
 - lib/rodauth/rails/app.rb
 - lib/rodauth/rails/app/flash.rb
+- lib/rodauth/rails/app/middleware.rb
 - lib/rodauth/rails/controller_methods.rb
 - lib/rodauth/rails/feature.rb
 - lib/rodauth/rails/middleware.rb

data/lib/rodauth/features/rails.rb

@@ -1 +0,0 @@
-require "rodauth/rails/feature"