two_step 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 37a12a608ceb35e05197580c831770a73bf341a148f811aab06cdb22e42fc00b
+  data.tar.gz: c6b73ff378950bde63adafc2f1166ddabf58d8209714043cdcacd58ad2a66a7e
+SHA512:
+  metadata.gz: 5d56b0ef8afc9d883bf542009ea17ccd05c0ff982d2b86cff90e7c3eae94917c5ab61953f060e84934bae59d95aa7ce382f7fcc1333efa5482513d40daf9d99e
+  data.tar.gz: 983f9d818207b64651b4f4432c02a3b323a0b9f99f7cab4552014b1e2df3235d73a40c8e5481bf708b7745427555e4fdb211d69c605e0aeca35de642a151c47c

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## [1.0.0] - 2026-05-23
+
+Initial release.
+
+### Added
+
+- Mountable Rails engine for TOTP-based multi-factor authentication in session-based applications
+- `TwoStep::Models::Authenticatable` concern for OTP secrets, provisioning URIs, replay protection, backup code generation, and backup code consumption
+- TwoStep setup and challenge flows with QR-code enrollment, manual setup key fallback, TOTP verification, and one-time backup code support
+- Install generator that creates the initializer and migration for `otp_secret`, `otp_required_for_login`, `otp_backup_codes`, and `last_otp_at`
+- Configurable host-app integration hooks for pending resource lookup, current resource lookup, redirects, session completion, and layout metadata
+- Built-in engine views, styles, routes, and English/Japanese translations
+
+### Security
+
+- Backup codes stored as digests by default and verified with constant-time comparison
+- Replay protection for TOTP codes via `last_otp_at`
+- Safe relative-path handling for setup disable redirects
+- Support for encrypted `otp_secret` storage in host applications

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,220 @@
+# TwoStep
+
+`two_step` is a mountable Rails engine that adds TOTP-based multi-factor authentication to session-based Rails apps. It stays out of the password step, so it works with custom authentication flows as well as libraries such as Clearance or Sorcery.
+
+## Features
+
+- TOTP verification compatible with Google Authenticator, 1Password, Authy, and similar apps
+- QR-code enrollment with a manual setup key fallback
+- One-time backup codes in the format `XXX-XXX-XXX-XXX-XXX`
+- SHA-256 backup code digests by default, with configurable digest and verify hooks
+- Replay protection through `last_otp_at`
+- Mountable engine with isolated controllers, routes, views, locales, and assets
+- Built-in English and Japanese copy plus a branded default UI
+- Host-application hooks for resource lookup, redirects, layout metadata, and post-TwoStep session handling
+
+## Requirements
+
+- Ruby `>= 3.2`
+- Rails `>= 7.1`
+
+## Installation
+
+Add the gem and install:
+
+```ruby
+gem "two_step"
+```
+
+```bash
+bundle install
+bin/rails generate two_step:install
+bin/rails db:migrate
+```
+
+If you use a model other than `User`, pass it to the generator:
+
+```bash
+bin/rails generate two_step:install --model Admin
+```
+
+Include the concern in your authenticatable model:
+
+```ruby
+class User < ApplicationRecord
+  include TwoStep::Models::Authenticatable
+  encrypts :otp_secret
+end
+```
+
+`encrypts :otp_secret` is recommended on Rails 7+ so the shared secret is not stored in plaintext.
+
+Mount the engine:
+
+```ruby
+Rails.application.routes.draw do
+  mount TwoStep::Engine => "/two_step"
+end
+```
+
+The generator creates `config/initializers/two_step.rb` and a migration that adds:
+
+- `otp_secret`
+- `otp_required_for_login`
+- `otp_backup_codes`
+- `last_otp_at`
+
+## Quick Start
+
+The host app handles the password step first and redirects into the engine only when TwoStep is required.
+
+```ruby
+class SessionsController < ApplicationController
+  def create
+    user = User.authenticate_by(email: params[:email], password: params[:password])
+
+    if user&.otp_enabled?
+      reset_session
+      session[:two_step_pending_user_id] = user.id
+      redirect_to two_step.new_two_step_challenge_path
+    elsif user
+      reset_session
+      session[:user_id] = user.id
+      redirect_to dashboard_path
+    else
+      flash.now[:alert] = "Invalid email or password"
+      render :new, status: :unprocessable_entity
+    end
+  end
+end
+```
+
+The setup screen can be used from an already signed-in security settings page or from a pending-login flow. When setup succeeds for a pending-login user, the engine runs your `on_authentication_success` hook immediately.
+
+## Routes
+
+| Route | Purpose |
+| --- | --- |
+| `GET /two_step/setup/new` | Show the QR code, manual key, and enrollment form |
+| `POST /two_step/setup` | Verify the first TOTP code, enable TwoStep, and reveal backup codes |
+| `POST /two_step/setup/disable` | Disable TwoStep and clear secrets, backup codes, and replay state |
+| `GET /two_step/challenge/new` | Prompt for a TOTP code or backup code |
+| `POST /two_step/challenge` | Complete the TwoStep challenge |
+
+`POST /two_step/setup/disable` also accepts an optional `return_to` parameter, but only relative paths beginning with `/` are honored.
+
+## Configuration
+
+The initializer is the public integration contract between the engine and your app:
+
+```ruby
+TwoStep.configure do |config|
+  config.issuer = "MyApp"
+  config.backup_code_count = 10
+  config.qr_code_module_size = 4
+  config.otp_drift_behind = 30
+  config.otp_drift_ahead = 30
+
+  config.resource_finder = ->(session) {
+    User.find_by(id: session[:two_step_pending_user_id])
+  }
+
+  config.current_resource_finder = ->(session) {
+    User.find_by(id: session[:user_id])
+  }
+
+  config.login_path = "/login"
+  config.after_two_step_login_path = "/"
+
+  config.on_authentication_success = ->(resource, session, _controller) {
+    session.delete(:two_step_pending_user_id)
+    session[:user_id] = resource.id
+  }
+
+  config.layout_title = -> { "#{config.issuer} Security" }
+  config.layout_stylesheets = ["two_step/application"]
+  config.layout_html_attributes = -> { {lang: I18n.locale} }
+  config.layout_body_attributes = {class: "two_step-shell"}
+  config.layout_brand = -> { config.issuer }
+end
+```
+
+Notes:
+
+- `resource_finder` and `current_resource_finder` may accept either `session` alone or `session, controller`.
+- `login_path` can be a string or a callable that receives `controller`.
+- `after_two_step_login_path` can be a string or a callable that receives `resource, controller`.
+- `on_authentication_success` can accept `resource, session` or `resource, session, controller`.
+- `layout_title`, `layout_stylesheets`, `layout_html_attributes`, `layout_body_attributes`, and `layout_brand` can be plain values or callables that receive `controller`.
+
+Example using controller-aware hooks:
+
+```ruby
+TwoStep.configure do |config|
+  config.login_path = ->(controller) { controller.main_app.login_path }
+  config.after_two_step_login_path = ->(_resource, controller) { controller.main_app.dashboard_path }
+
+  config.on_authentication_success = lambda do |resource, _session, controller|
+    controller.reset_session
+    controller.session[:user_id] = resource.id
+  end
+
+  config.layout_stylesheets = ["two_step/application", "two_step/host"]
+  config.layout_body_attributes = ->(controller) {
+    {class: "two_step-shell", data: {screen: controller.action_name}}
+  }
+end
+```
+
+## Backup Codes
+
+Generated backup codes use uppercase letters and digits `2-9`, excluding ambiguous characters such as `I`, `L`, and `O`. Users can enter them with or without separators.
+
+By default, the engine stores backup codes as SHA-256 digests and verifies them with a constant-time comparison:
+
+```ruby
+config.backup_code_digest_method = ->(normalized_code) {
+  Digest::SHA256.hexdigest(normalized_code)
+}
+
+config.backup_code_verify_method = ->(normalized_code, hashed_code) {
+  Rack::Utils.secure_compare(Digest::SHA256.hexdigest(normalized_code), hashed_code)
+}
+```
+
+You can replace both hooks if your application needs a different storage strategy.
+
+## Security Notes
+
+- Encrypt `otp_secret` when your app supports Active Record encryption.
+- Rotate the session after password authentication, and optionally again after TwoStep completes.
+- Rate-limit both password and TwoStep endpoints in the host application.
+- Treat backup codes like passwords: display them once, store them hashed, and never log them.
+- The setup screen preserves an existing secret until TwoStep is explicitly disabled, which avoids breaking a user's authenticator app on refresh.
+
+## Customization
+
+- Override engine views by copying templates from `app/views/two_step/...` into the host app.
+- Add host stylesheets and list them in `config.layout_stylesheets`.
+- Customize page title, brand label, HTML attributes, and body attributes through the layout hooks.
+- Use the controller-aware callbacks when you need host route helpers or custom session behavior.
+- Switch locales through normal Rails I18n handling; the engine ships with English and Japanese translations.
+
+## Development
+
+This repository uses [Standard](https://github.com/standardrb/standard) with `standard-rails`.
+
+```bash
+bin/setup
+bin/lint
+bin/test
+bundle exec rake coverage
+docker compose build test
+docker compose run --rm test
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines and [SECURITY.md](SECURITY.md) for responsible disclosure.
+
+## License
+
+MIT. See [MIT-LICENSE](MIT-LICENSE).

data/Rakefile

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"
+
+desc "Run the engine test suite"
+task :test do
+  if ENV["COVERAGE"]
+    Rake::Task["coverage"].invoke
+  else
+    Rake::Task["app:test"].invoke
+  end
+end
+
+desc "Run tests with SimpleCov (100% threshold)"
+task :coverage do
+  ENV["COVERAGE"] = "1"
+
+  sh(
+    "bundle",
+    "exec",
+    "ruby",
+    "-Itest",
+    "-e",
+    'Dir["test/**/*_test.rb"].sort.each { |file| require File.expand_path(file) }'
+  )
+end

data/app/assets/stylesheets/two_step/application.css

@@ -0,0 +1,259 @@
+/*
+ *= require_self
+ */
+
+:root {
+  --two_step-bg: radial-gradient(circle at 20% 20%, #f8efe3 0%, #fdf7ef 42%, #ffffff 100%);
+  --two_step-surface: #ffffff;
+  --two_step-border: #d9cbb4;
+  --two_step-text: #26170d;
+  --two_step-muted: #6e5a45;
+  --two_step-accent: #9b4626;
+  --two_step-accent-dark: #78341b;
+  --two_step-accent-soft: #f9eee8;
+  --two_step-success-bg: #eef7ee;
+  --two_step-success-border: #7ca67d;
+  --two_step-alert-bg: #fff1ec;
+  --two_step-alert-border: #d97857;
+  --two_step-warning-bg: #fff8ed;
+  --two_step-warning-border: #d9a861;
+}
+
+body.two_step-shell {
+  margin: 0;
+  min-height: 100vh;
+  background: var(--two_step-bg);
+  color: var(--two_step-text);
+  font-family: "Avenir Next", "Segoe UI", "Helvetica Neue", sans-serif;
+  position: relative;
+}
+
+.two_step-shell__mesh {
+  position: fixed;
+  inset: 0;
+  background-image: radial-gradient(rgba(155, 70, 38, 0.08) 0.06rem, transparent 0.06rem);
+  background-size: 1.35rem 1.35rem;
+  pointer-events: none;
+}
+
+.two_step-card {
+  position: relative;
+  z-index: 1;
+  box-sizing: border-box;
+  width: min(34rem, calc(100% - 2rem));
+  margin: 2.5rem auto;
+  padding: 2rem;
+  background: var(--two_step-surface);
+  border: 1px solid var(--two_step-border);
+  border-radius: 1.25rem;
+  box-shadow: 0 1.5rem 4rem rgba(35, 24, 13, 0.12);
+}
+
+.two_step-brand {
+  margin: 0 0 1.2rem;
+  font-size: 0.82rem;
+  font-weight: 700;
+  letter-spacing: 0.12em;
+  color: var(--two_step-muted);
+  text-transform: uppercase;
+}
+
+.two_step-header {
+  display: grid;
+  gap: 0.5rem;
+}
+
+.two_step-kicker {
+  margin: 0;
+  color: var(--two_step-accent);
+  font-size: 0.85rem;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.two_step-card h1 {
+  margin-top: 0;
+  margin-bottom: 0;
+  font-size: clamp(1.8rem, 4vw, 2.2rem);
+  line-height: 1.1;
+}
+
+.two_step-copy,
+.two_step-manual-key,
+.two_step-actions {
+  margin-top: 0.2rem;
+  margin-bottom: 0;
+  color: var(--two_step-muted);
+}
+
+.two_step-badge {
+  display: inline-flex;
+  align-items: center;
+  width: fit-content;
+  margin: 0.4rem 0 0;
+  padding: 0.35rem 0.7rem;
+  border-radius: 999px;
+  border: 1px solid var(--two_step-warning-border);
+  background: var(--two_step-warning-bg);
+  color: #7b4d13;
+  font-size: 0.82rem;
+  font-weight: 600;
+}
+
+.two_step-steps {
+  margin: 1.25rem 0 0;
+  padding-left: 1.2rem;
+  color: var(--two_step-muted);
+  display: grid;
+  gap: 0.3rem;
+}
+
+.two_step-qr {
+  display: flex;
+  justify-content: center;
+  padding: 1rem;
+  margin: 1rem 0;
+  background: #fffaf4;
+  border: 1px solid var(--two_step-border);
+  border-radius: 1rem;
+}
+
+.two_step-form {
+  display: grid;
+  gap: 1rem;
+  margin-top: 1.5rem;
+}
+
+.two_step-field {
+  display: grid;
+  gap: 0.4rem;
+}
+
+.two_step-card input[type="text"] {
+  width: 100%;
+  box-sizing: border-box;
+  padding: 0.85rem 1rem;
+  border: 1px solid var(--two_step-border);
+  border-radius: 0.85rem;
+  font: inherit;
+  transition: border-color 0.15s ease, box-shadow 0.15s ease;
+}
+
+.two_step-card input[type="text"]:focus {
+  outline: none;
+  border-color: var(--two_step-accent);
+  box-shadow: 0 0 0 0.2rem rgba(155, 70, 38, 0.15);
+}
+
+.two_step-card input[type="submit"] {
+  border: 0;
+  border-radius: 999px;
+  padding: 0.85rem 1.2rem;
+  background: var(--two_step-accent);
+  color: #ffffff;
+  font: inherit;
+  font-weight: 600;
+  cursor: pointer;
+}
+
+.two_step-card input[type="submit"]:hover {
+  background: var(--two_step-accent-dark);
+}
+
+.two_step-field-note {
+  margin: 0;
+  color: var(--two_step-muted);
+  font-size: 0.84rem;
+}
+
+.two_step-details {
+  margin-top: 1.5rem;
+  padding-top: 1rem;
+  border-top: 1px solid var(--two_step-border);
+}
+
+.two_step-details summary {
+  cursor: pointer;
+  font-weight: 600;
+}
+
+.two_step-details .two_step-copy {
+  margin-top: 0.7rem;
+}
+
+.two_step-warning {
+  margin-top: 1.1rem;
+  padding: 0.9rem 1rem;
+  border-radius: 0.85rem;
+  border: 1px solid var(--two_step-warning-border);
+  background: var(--two_step-warning-bg);
+}
+
+.two_step-warning p {
+  margin: 0.35rem 0 0;
+  color: #735232;
+}
+
+.two_step-backup-codes {
+  margin-top: 1rem;
+  padding-left: 1.25rem;
+  display: grid;
+  gap: 0.35rem;
+}
+
+.two_step-backup-codes code,
+.two_step-manual-key code {
+  font-size: 0.95rem;
+  background: #fbf5ee;
+  padding: 0.18rem 0.4rem;
+  border-radius: 0.4rem;
+}
+
+.two_step-actions {
+  margin-top: 1.3rem;
+}
+
+.two_step-link-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 999px;
+  background: var(--two_step-accent);
+  color: #fff;
+  text-decoration: none;
+  padding: 0.72rem 1.1rem;
+  font-weight: 600;
+}
+
+.two_step-link-button:hover {
+  background: var(--two_step-accent-dark);
+}
+
+.two_step-flash {
+  margin-top: 0;
+  margin-bottom: 1rem;
+  padding: 0.85rem 1rem;
+  border-radius: 0.85rem;
+}
+
+.two_step-flash--notice {
+  background: var(--two_step-success-bg);
+  border: 1px solid var(--two_step-success-border);
+}
+
+.two_step-flash--alert {
+  background: var(--two_step-alert-bg);
+  border: 1px solid var(--two_step-alert-border);
+}
+
+@media (max-width: 640px) {
+  .two_step-card {
+    margin: 1.5rem auto;
+    padding: 1.25rem;
+  }
+
+  .two_step-steps {
+    margin-top: 1rem;
+  }
+}

data/app/controllers/two_step/application_controller.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module TwoStep
+  # Base for all engine controllers. Namespace isolation keeps routes, helpers,
+  # and constants separate from the host application (see TwoStep::Engine).
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+  end
+end

data/app/controllers/two_step/two_step_challenges_controller.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module TwoStep
+  class TwoStepChallengesController < ApplicationController
+    before_action :require_pending_resource
+
+    def new
+    end
+
+    def create
+      resource = pending_resource
+      if params[:backup_code].present?
+        verify_backup(resource)
+      else
+        verify_otp(resource)
+      end
+    end
+
+    private
+
+    def verify_backup(resource)
+      if resource.consume_backup_code(params[:backup_code])
+        complete_two_step(resource)
+      else
+        flash.now[:alert] = I18n.t("two_step.challenges.invalid_backup")
+        render :new, status: 422
+      end
+    end
+
+    def verify_otp(resource)
+      if resource.verify_otp(params[:otp_code])
+        complete_two_step(resource)
+      else
+        flash.now[:alert] = I18n.t("two_step.challenges.invalid_otp")
+        render :new, status: 422
+      end
+    end
+
+    def pending_resource
+      @pending_resource ||= TwoStep.configuration.find_pending_resource(session, controller: self)
+    end
+
+    def require_pending_resource
+      redirect_to TwoStep.configuration.resolve_login_path(controller: self) unless pending_resource
+    end
+
+    def complete_two_step(resource)
+      TwoStep.configuration.run_authentication_success(resource, session, controller: self)
+      redirect_to TwoStep.configuration.resolve_after_two_step_login_path(resource, controller: self)
+    end
+  end
+end

data/app/controllers/two_step/two_step_setups_controller.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module TwoStep
+  class TwoStepSetupsController < ApplicationController
+    before_action :require_setup_resource, only: %i[new create]
+    before_action :require_current_resource, only: :disable
+
+    helper_method :current_resource, :setup_resource, :setup_requires_login_challenge?
+
+    def new
+      setup_resource.ensure_otp_secret!
+      @qr_svg = generate_qr_svg(setup_resource.otp_provisioning_uri)
+    end
+
+    def create
+      if setup_resource.verify_otp(params[:otp_code])
+        setup_resource.update_columns(otp_required_for_login: true)
+        @backup_codes = setup_resource.generate_backup_codes!
+
+        if setup_requires_login_challenge?
+          TwoStep.configuration.run_authentication_success(setup_resource, session, controller: self)
+        end
+
+        render :complete
+      else
+        flash.now[:alert] = I18n.t("two_step.setups.invalid_otp")
+        @qr_svg = generate_qr_svg(setup_resource.otp_provisioning_uri)
+        render :new, status: :unprocessable_content
+      end
+    end
+
+    def disable
+      current_resource.disable_otp!
+      redirect_to(
+        disable_redirect_path || TwoStep.configuration.resolve_after_two_step_login_path(current_resource, controller: self),
+        notice: I18n.t("two_step.setups.disabled")
+      )
+    end
+
+    private
+
+    def current_resource
+      @current_resource ||= TwoStep.configuration.find_current_resource(session, controller: self)
+    end
+
+    def setup_resource
+      @setup_resource ||= current_resource || TwoStep.configuration.find_pending_resource(session, controller: self)
+    end
+
+    def setup_requires_login_challenge?
+      setup_resource.present? && current_resource.blank?
+    end
+
+    def require_setup_resource
+      redirect_to TwoStep.configuration.resolve_login_path(controller: self) unless setup_resource
+    end
+
+    def require_current_resource
+      redirect_to TwoStep.configuration.resolve_login_path(controller: self) unless current_resource
+    end
+
+    def generate_qr_svg(uri)
+      RQRCode::QRCode.new(uri).as_svg(
+        module_size: TwoStep.configuration.qr_code_module_size,
+        standalone: true,
+        use_path: true
+      ).html_safe
+    end
+
+    def disable_redirect_path
+      candidate = params[:return_to].to_s
+      return if candidate.blank?
+      return if !candidate.start_with?("/") || candidate.start_with?("//")
+
+      candidate
+    end
+  end
+end