rails_authentication 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 305e121fa18342571e89ab2bee6cf11f34ba708c08c2c17fb85e5880b2f0ab56
+  data.tar.gz: b62fec7dddeaf09e159321f396b2723f3b5793f7c71fc72af3044c49987e6c86
+SHA512:
+  metadata.gz: b35c71dd413c7e12398bdfd2b04f78e2e5669484254af2c9125958a69072ff2904d41bf858800f3853a48fb5aac20616425ae438407df8ed9045db742e6d0d8e
+  data.tar.gz: dfa8c8b76bff7b8d907bda610db59b3fd8fbbf580722f659f20cef9c2153b6ea56f69d531a879dded44d94820748074bb88f8da4f2397c61c2c3e778e68ff47a

data/README.md

@@ -0,0 +1,108 @@
+# rails_authentication
+
+Devise-style features on top of Rails 8's built-in authentication generator.
+
+Rails 8's `bin/rails generate authentication` gives you the essentials: a `User` model with
+`has_secure_password`, database-backed sessions, sign-in/sign-out, and a password reset flow. This
+gem extends that same command to also install:
+
+| Feature | What it does |
+| --- | --- |
+| **Confirmable** | Emails confirmation instructions; blocks sign-in until the email address is confirmed |
+| **Recoverable** | Password reset with DB-backed, revocable, expiring tokens (replaces the base stateless tokens) |
+| **Registerable** | Sign-up, plus account editing and deletion |
+| **Rememberable** | "Remember me" checkbox — persistent cookie only when checked |
+| **Trackable** | Records every sign-in attempt (success and failure) in a `user_auths` table: IP, user agent, referrer, failure reason |
+| **Timeoutable** | Expires sessions after 30 minutes of inactivity |
+| **Validatable** | Email format/uniqueness, password length, and password complexity validations |
+| **Lockable** | Locks the account after 5 failed attempts; unlock via email or automatically after 1 hour |
+| **Invitable** | Invite users by email; they accept by choosing their own password |
+
+Everything is **generated into your app** as plain, readable code — controllers, views, mailers,
+migrations, and one model concern per feature. There is no runtime dependency on this gem: after
+generating, the code is yours to edit.
+
+This gem is meant to be installed temporarily. Install it long enough to run the generators and uninstall it after. If you keep it installed, keep it in the `development` group.
+
+## Installation
+
+Requires Rails >= 8.0 and, for the email-driven features (Confirmable, Recoverable, Lockable,
+Invitable), Action Mailer.
+
+```ruby
+# Gemfile
+group :development do
+  gem "rails_authentication"
+end
+```
+
+## Usage
+
+```sh
+bin/rails generate authentication
+bin/rails db:migrate
+```
+
+That single command runs Rails' built-in authentication generator first, then layers every feature
+on top. Skip any feature you don't want:
+
+```sh
+bin/rails generate authentication --skip-invitable --skip-trackable
+```
+
+Available flags: `--skip-confirmable`, `--skip-recoverable`, `--skip-registerable`,
+`--skip-rememberable`, `--skip-trackable`, `--skip-timeoutable`, `--skip-validatable`,
+`--skip-lockable`, `--skip-invitable`, and `--reconfirmable` (Confirmable: postpone email address
+changes until the new address is confirmed, via an `unconfirmed_email` column).
+
+Each feature adds a single `include <Feature>Concern` line to `app/models/user.rb`; all of its
+model behavior lives in `app/models/concerns/<feature>_concern.rb`. Tunables are plain constants in
+the generated concerns — e.g. `TimeoutableConcern::TIMEOUT_IN`, `LockableConcern::MAXIMUM_ATTEMPTS`,
+`LockableConcern::UNLOCK_IN`, `ConfirmableConcern::CONFIRMATION_TOKEN_EXPIRES_IN`,
+`ValidatableConcern::PASSWORD_LENGTH`, `ValidatableConcern::PASSWORD_MINIMUM_COMPLEXITY` — edit them
+there. Concerns keep the model clean.
+
+### Generated routes
+
+```
+resource  :registration, only: %i[ new create edit update destroy ]
+resources :confirmations, only: %i[ new create show ], param: :token
+resources :unlocks,       only: %i[ new create show ], param: :token
+resources :invitations,   only: %i[ new create edit update ], param: :token
+resource  :session                      # from the base generator
+resources :passwords, param: :token     # from the base generator
+```
+
+### Notes
+
+- **Existing users + Confirmable**: sign-in requires `confirmed_at`, so backfill it when adding
+  Confirmable to an app with existing users:
+  `User.update_all(confirmed_at: Time.current)`.
+- **Recoverable** replaces the base generator's `PasswordsController`/`PasswordsMailer` (which use
+  stateless signed tokens) with DB-token versions. If you `--skip-recoverable`, the base flow is
+  left untouched.
+- The generator overwrites the base generator's `SessionsController`, `Authentication` concern, and
+  sessions view with versions tailored to the features you selected. Run the generator once, up
+  front — re-running it after you've customized those files will prompt to overwrite them.
+
+## Future Plans
+
+- OTP (Google Authenticator)
+- Passwordless (code emailed)
+
+## Development
+
+```sh
+bundle install
+bundle exec rake spec:generators   # generator specs (fast, no app boot)
+bundle exec rake dummy:prepare     # build spec/dummy by running the real generator
+bundle exec rake spec:requests     # request specs against spec/dummy
+bundle exec rspec spec/generators/lockable_spec.rb:12   # a single example
+```
+
+`spec/dummy` is generated (and gitignored), never hand-maintained, so the request specs always
+exercise exactly what the templates produce.
+
+## License
+
+MIT

data/lib/generators/authentication/authentication_generator.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+require_relative "features/confirmable"
+require_relative "features/recoverable"
+require_relative "features/registerable"
+require_relative "features/rememberable"
+require_relative "features/trackable"
+require_relative "features/timeoutable"
+require_relative "features/validatable"
+require_relative "features/lockable"
+require_relative "features/invitable"
+
+module RailsAuthentication
+  module Generators
+    # Shadows Rails' built-in `bin/rails generate authentication` command: the explicit
+    # `authentication:authentication` namespace is checked before Rails' own
+    # `rails:authentication`, so the bare `authentication` invocation lands here.
+    # It runs the built-in generator first, then layers the feature set on top.
+    #
+    # The Ruby namespace is RailsAuthentication (not Authentication, which would give the
+    # same Thor namespace implicitly) because Rails 8's base generator creates an
+    # `Authentication` controller concern in the host app — a top-level constant this gem
+    # must not squat on.
+    class AuthenticationGenerator < Rails::Generators::Base
+      namespace "authentication:authentication"
+
+      FEATURES = %i[
+        confirmable recoverable registerable rememberable trackable
+        timeoutable validatable lockable invitable
+      ].freeze
+
+      include ActiveRecord::Generators::Migration
+
+      include Features::Confirmable
+      include Features::Recoverable
+      include Features::Registerable
+      include Features::Rememberable
+      include Features::Trackable
+      include Features::Timeoutable
+      include Features::Validatable
+      include Features::Lockable
+      include Features::Invitable
+
+      source_root File.expand_path("templates", __dir__)
+
+      FEATURES.each do |feature|
+        class_option :"skip_#{feature}", type: :boolean, default: false,
+          desc: "Skip #{feature}"
+      end
+
+      class_option :reconfirmable, type: :boolean, default: false,
+        desc: "Confirmable: postpone email address changes until reconfirmed (adds unconfirmed_email column)"
+
+      def install_base_authentication
+        say "Running Rails' built-in authentication generator", :green
+        Rails::Generators.invoke("rails:authentication", [], behavior: behavior, destination_root: destination_root)
+      end
+
+      def install_validatable
+        generate_validatable if validatable?
+      end
+
+      def install_registerable
+        generate_registerable if registerable?
+      end
+
+      def install_recoverable
+        generate_recoverable if recoverable?
+      end
+
+      def install_confirmable
+        generate_confirmable if confirmable?
+      end
+
+      def install_rememberable
+        generate_rememberable if rememberable?
+      end
+
+      def install_trackable
+        generate_trackable if trackable?
+      end
+
+      def install_timeoutable
+        generate_timeoutable if timeoutable?
+      end
+
+      def install_lockable
+        generate_lockable if lockable?
+      end
+
+      def install_invitable
+        generate_invitable if invitable?
+      end
+
+      # Confirmable, Rememberable, Trackable, Timeoutable, and Lockable all hook into the
+      # sign-in flow, so the base generator's session files are replaced with versions
+      # rendered from the enabled feature set. Overwriting is safe: the base copies were
+      # written moments ago by this same run.
+      def customize_session_layer
+        template "app/controllers/sessions_controller.rb", force: true
+        template "app/controllers/concerns/authentication.rb", force: true
+        template "app/views/sessions/new.html.erb", force: true
+      end
+
+      no_commands do
+        FEATURES.each do |feature|
+          define_method(:"#{feature}?") { !options[:"skip_#{feature}"] }
+        end
+
+        def reconfirmable?
+          confirmable? && options[:reconfirmable]
+        end
+
+        def include_concern_in_user(concern)
+          inject_into_class "app/models/user.rb", "User", "  include #{concern}\n"
+        end
+
+        def migration_version
+          "[#{ActiveRecord::VERSION::STRING.to_f}]"
+        end
+      end
+    end
+  end
+end

data/lib/generators/authentication/features/confirmable.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module RailsAuthentication
+  module Generators
+    module Features
+      module Confirmable
+        private
+          def generate_confirmable
+            template "app/models/concerns/confirmable_concern.rb"
+            include_concern_in_user "ConfirmableConcern"
+            migration_template "db/migrate/add_confirmable_to_users.rb", "db/migrate/add_confirmable_to_users.rb"
+            template "app/controllers/confirmations_controller.rb"
+            template "app/views/confirmations/new.html.erb"
+            route "resources :confirmations, only: %i[ new create show ], param: :token"
+
+            if defined?(ActionMailer::Railtie)
+              template "app/mailers/confirmations_mailer.rb"
+              template "app/views/confirmations_mailer/confirmation_instructions.html.erb"
+              template "app/views/confirmations_mailer/confirmation_instructions.text.erb"
+            end
+          end
+      end
+    end
+  end
+end

data/lib/generators/authentication/features/invitable.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RailsAuthentication
+  module Generators
+    module Features
+      module Invitable
+        private
+          def generate_invitable
+            template "app/models/concerns/invitable_concern.rb"
+            include_concern_in_user "InvitableConcern"
+            migration_template "db/migrate/add_invitable_to_users.rb", "db/migrate/add_invitable_to_users.rb"
+            template "app/controllers/invitations_controller.rb"
+            template "app/views/invitations/new.html.erb"
+            template "app/views/invitations/edit.html.erb"
+            route "resources :invitations, only: %i[ new create edit update ], param: :token"
+
+            if defined?(ActionMailer::Railtie)
+              template "app/mailers/invitations_mailer.rb"
+              template "app/views/invitations_mailer/invitation_instructions.html.erb"
+              template "app/views/invitations_mailer/invitation_instructions.text.erb"
+            end
+          end
+      end
+    end
+  end
+end

data/lib/generators/authentication/features/lockable.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module RailsAuthentication
+  module Generators
+    module Features
+      module Lockable
+        private
+          def generate_lockable
+            template "app/models/concerns/lockable_concern.rb"
+            include_concern_in_user "LockableConcern"
+            migration_template "db/migrate/add_lockable_to_users.rb", "db/migrate/add_lockable_to_users.rb"
+            template "app/controllers/unlocks_controller.rb"
+            template "app/views/unlocks/new.html.erb"
+            route "resources :unlocks, only: %i[ new create show ], param: :token"
+
+            if defined?(ActionMailer::Railtie)
+              template "app/mailers/unlocks_mailer.rb"
+              template "app/views/unlocks_mailer/unlock_instructions.html.erb"
+              template "app/views/unlocks_mailer/unlock_instructions.text.erb"
+            end
+          end
+      end
+    end
+  end
+end

data/lib/generators/authentication/features/recoverable.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module RailsAuthentication
+  module Generators
+    module Features
+      module Recoverable
+        private
+          # Replaces the base generator's stateless generates_token_for password reset
+          # with DB-backed, revocable tokens.
+          def generate_recoverable
+            template "app/models/concerns/recoverable_concern.rb"
+            include_concern_in_user "RecoverableConcern"
+            migration_template "db/migrate/add_recoverable_to_users.rb", "db/migrate/add_recoverable_to_users.rb"
+            template "app/controllers/passwords_controller.rb", force: true
+
+            if defined?(ActionMailer::Railtie)
+              template "app/mailers/passwords_mailer.rb", force: true
+              template "app/views/passwords_mailer/reset.html.erb", force: true
+              template "app/views/passwords_mailer/reset.text.erb", force: true
+            end
+          end
+      end
+    end
+  end
+end

data/lib/generators/authentication/features/registerable.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RailsAuthentication
+  module Generators
+    module Features
+      module Registerable
+        private
+          def generate_registerable
+            template "app/controllers/registrations_controller.rb"
+            template "app/views/registrations/new.html.erb"
+            template "app/views/registrations/edit.html.erb"
+            route "resource :registration, only: %i[ new create edit update destroy ]"
+          end
+      end
+    end
+  end
+end

data/lib/generators/authentication/features/rememberable.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module RailsAuthentication
+  module Generators
+    module Features
+      module Rememberable
+        private
+          def generate_rememberable
+            template "app/models/concerns/rememberable_concern.rb"
+            include_concern_in_user "RememberableConcern"
+            migration_template "db/migrate/add_rememberable_to_users.rb", "db/migrate/add_rememberable_to_users.rb"
+          end
+      end
+    end
+  end
+end

data/lib/generators/authentication/features/timeoutable.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RailsAuthentication
+  module Generators
+    module Features
+      module Timeoutable
+        private
+          # No migration: inactivity is measured against sessions.updated_at, which the
+          # base generator's sessions table already has.
+          def generate_timeoutable
+            template "app/models/concerns/timeoutable_concern.rb"
+            include_concern_in_user "TimeoutableConcern"
+          end
+      end
+    end
+  end
+end

data/lib/generators/authentication/features/trackable.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RailsAuthentication
+  module Generators
+    module Features
+      module Trackable
+        private
+          def generate_trackable
+            template "app/models/concerns/trackable_concern.rb"
+            include_concern_in_user "TrackableConcern"
+            template "app/models/user_auth.rb"
+            migration_template "db/migrate/create_user_auths.rb", "db/migrate/create_user_auths.rb"
+          end
+      end
+    end
+  end
+end

data/lib/generators/authentication/features/validatable.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RailsAuthentication
+  module Generators
+    module Features
+      module Validatable
+        private
+          def generate_validatable
+            template "app/models/concerns/validatable_concern.rb"
+            include_concern_in_user "ValidatableConcern"
+          end
+      end
+    end
+  end
+end

data/lib/generators/authentication/templates/app/controllers/concerns/authentication.rb.tt

@@ -0,0 +1,96 @@
+module Authentication
+  extend ActiveSupport::Concern
+
+  included do
+    before_action :require_authentication
+    helper_method :authenticated?, :current_user
+  end
+
+  class_methods do
+    def allow_unauthenticated_access(**options)
+      skip_before_action :require_authentication, **options
+    end
+  end
+
+  private
+
+  def authenticated?
+    resume_session
+  end
+
+  def current_user
+    Current.user
+  end
+
+  def require_authentication
+    resume_session || request_authentication
+  end
+
+  def resume_session
+    Current.session ||= find_session_by_cookie
+  end
+
+<% if timeoutable? -%>
+  def find_session_by_cookie
+    return unless cookies.signed[:session_id]
+    return unless session = Session.find_by(id: cookies.signed[:session_id])
+
+<% if rememberable? -%>
+    if !session.user.remembered? && session.user.timedout?(session.updated_at)
+<% else -%>
+    if session.user.timedout?(session.updated_at)
+<% end -%>
+      session.destroy
+      cookies.delete(:session_id)
+      nil
+    else
+      session.touch
+      session
+    end
+  end
+<% else -%>
+  def find_session_by_cookie
+    Session.find_by(id: cookies.signed[:session_id]) if cookies.signed[:session_id]
+  end
+<% end -%>
+
+  def request_authentication
+    session[:return_to_after_authenticating] = request.url
+    redirect_to new_session_path
+  end
+
+  def after_authentication_url
+    session.delete(:return_to_after_authenticating) || root_url
+  end
+
+<% if rememberable? -%>
+  def start_new_session_for(user, remember: false)
+    user.sessions.create!(user_agent: request.user_agent, ip_address: request.remote_ip).tap do |session|
+      Current.session = session
+
+      if remember
+        user.remember_me!
+        cookies.signed.permanent[:session_id] = { value: session.id, httponly: true, same_site: :lax }
+      else
+        user.forget_me!
+        cookies.signed[:session_id] = { value: session.id, httponly: true, same_site: :lax }
+      end
+    end
+  end
+<% else -%>
+  def start_new_session_for(user)
+    user.sessions.create!(user_agent: request.user_agent, ip_address: request.remote_ip).tap do |session|
+      Current.session = session
+      cookies.signed.permanent[:session_id] = { value: session.id, httponly: true, same_site: :lax }
+    end
+  end
+<% end -%>
+
+  def terminate_session
+<% if rememberable? -%>
+    Current.session.user.forget_me!
+<% end -%>
+    Current.session.destroy
+    cookies.delete(:session_id)
+  end
+end

data/lib/generators/authentication/templates/app/controllers/confirmations_controller.rb.tt

@@ -0,0 +1,27 @@
+class ConfirmationsController < ApplicationController
+  allow_unauthenticated_access
+  rate_limit to: 10, within: 3.minutes, only: :create, with: -> { redirect_to new_confirmation_path, alert: "Try again later." }
+
+  def new
+  end
+
+  def create
+    user = User.find_by(email_address: params[:email_address])
+<% if reconfirmable? -%>
+    user.send_confirmation_instructions if user && (!user.confirmed? || user.unconfirmed_email.present?)
+<% else -%>
+    user.send_confirmation_instructions if user && !user.confirmed?
+<% end -%>
+
+    redirect_to new_session_path, notice: "Confirmation instructions sent (if user with that email address exists and is unconfirmed)."
+  end
+
+  def show
+    if user = User.find_by_valid_confirmation_token(params[:token])
+      user.confirm!
+      redirect_to new_session_path, notice: "Your email address has been confirmed. Please sign in."
+    else
+      redirect_to new_confirmation_path, alert: "Confirmation link is invalid or has expired."
+    end
+  end
+end

data/lib/generators/authentication/templates/app/controllers/invitations_controller.rb.tt

@@ -0,0 +1,36 @@
+class InvitationsController < ApplicationController
+  allow_unauthenticated_access only: %i[ edit update ]
+  before_action :set_user_by_token, only: %i[ edit update ]
+
+  def new
+  end
+
+  def create
+    user = User.invite!(params[:email_address], invited_by: Current.user)
+
+    if user.persisted?
+      redirect_to new_invitation_path, notice: "Invitation sent to #{user.email_address}."
+    else
+      redirect_to new_invitation_path, alert: user.errors.full_messages.to_sentence
+    end
+  end
+
+  def edit
+  end
+
+  def update
+    if @user.accept_invitation!(password: params[:password], password_confirmation: params[:password_confirmation])
+      start_new_session_for @user
+      redirect_to after_authentication_url, notice: "Welcome! Your account is ready."
+    else
+      redirect_to edit_invitation_path(params[:token]), alert: @user.errors.full_messages.to_sentence
+    end
+  end
+
+  private
+
+  def set_user_by_token
+    @user = User.find_by_valid_invitation_token(params[:token])
+    redirect_to new_session_path, alert: "Invitation link is invalid or has expired." unless @user
+  end
+end

data/lib/generators/authentication/templates/app/controllers/passwords_controller.rb.tt

@@ -0,0 +1,39 @@
+class PasswordsController < ApplicationController
+  allow_unauthenticated_access
+  before_action :set_user_by_token, only: %i[ edit update ]
+  rate_limit to: 10, within: 3.minutes, only: :create, with: -> { redirect_to new_password_path, alert: "Try again later." }
+
+  def new
+  end
+
+  def create
+    if user = User.find_by(email_address: params[:email_address])
+      user.send_reset_password_instructions
+    end
+
+    redirect_to new_session_path, notice: "Password reset instructions sent (if user with that email address exists)."
+  end
+
+  def edit
+  end
+
+  def update
+    if @user.update(params.permit(:password, :password_confirmation))
+      @user.clear_reset_password_token!
+<% if lockable? -%>
+      @user.unlock!
+<% end -%>
+      @user.sessions.destroy_all
+      redirect_to new_session_path, notice: "Password has been reset."
+    else
+      redirect_to edit_password_path(params[:token]), alert: "Passwords did not match."
+    end
+  end
+
+  private
+
+  def set_user_by_token
+    @user = User.find_by_valid_reset_password_token(params[:token])
+    redirect_to new_password_path, alert: "Password reset link is invalid or has expired." unless @user
+  end
+end