rails_mfa 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4022b6c7e142e946603768e2ff0066f3a2698c3b20a663fe29305ac670b8fcfc
+  data.tar.gz: 077046b6cbb8a8261bfc4f9942df3779b6a1dd9d062853d61abc43224abb8c35
+SHA512:
+  metadata.gz: 9d9dd6854a9209dc5cb45390148f7f965d8106b29ad34203c528f277bb84ccb2c5a8d4393811b0579092cf7bdae52803671119c8c90415f5449ac666e401fb22
+  data.tar.gz: 751deab61328d9e39d12bccbbd057ab719db5afca3bc8973993bd225574b9a9abd686dd1abed19b650f3fe8e80365992c84909c0831f888922229783cab837a5

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  TargetRubyVersion: 3.1
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Rails generators for easy installation and setup
+  - `rails generate rails_mfa:install` - Creates initializer with configuration examples
+  - `rails generate rails_mfa:migration User` - Generates migration for MFA columns
+- Enhanced documentation with provider-agnostic examples
+- Multiple SMS provider examples (Twilio, AWS SNS, Vonage, MessageBird, Plivo)
+- Multiple email provider examples (SendGrid, ActionMailer, Postmark)
+- Complete authenticator app (TOTP) setup guide with QR code generation
+- Dedicated controller examples for authenticator app setup flow
+- Improved README emphasizing provider-agnostic nature
+
+## [0.1.0] - 2025-11-06
+
+### Added
+- Initial release of RailsMFA gem
+- Support for SMS-based multi-factor authentication
+- Support for email-based multi-factor authentication
+- Support for TOTP authenticator apps (Google Authenticator, Authy, 1Password, Microsoft Authenticator)
+- `RailsMFA::Model` concern for easy integration with any user model
+- `RailsMFA::TokenManager` for secure token generation and verification
+- `RailsMFA::Configuration` for flexible gem configuration
+- Pluggable SMS and email delivery providers via lambdas
+- Built-in QR code generation support via `rqrcode` gem
+- Timing-safe token comparison using ActiveSupport::SecurityUtils
+- One-time use tokens with automatic deletion after verification
+- Configurable token expiration (default: 5 minutes)
+- Configurable token length (default: 6 digits)
+- SimpleStore fallback for applications without Rails.cache
+- Provider-agnostic design compatible with Devise, Authlogic, and custom auth systems
+- Comprehensive RSpec test suite (52 examples, 0 failures)
+- Detailed documentation with integration examples

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Shoaib Malik
+
+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,614 @@
+# RailsMFA
+
+A pluggable, provider-agnostic multi-factor authentication (MFA/2FA) gem for Ruby on Rails applications. RailsMFA makes it simple to add secure authentication via SMS, email, or authenticator apps (TOTP) to any Rails application, regardless of your authentication system.
+
+## Features
+
+- **Multiple Authentication Methods**: Support for SMS, email, and TOTP-based authenticator apps (like Google Authenticator, Authy, 1Password, Microsoft Authenticator)
+- **Fully Provider Agnostic**: Works with ANY SMS provider (Twilio, AWS SNS, Vonage, MessageBird, etc.) and ANY authentication system (Devise, Authlogic, Clearance, or custom)
+- **Pluggable Delivery**: Easy-to-customize SMS and email delivery adapters - bring your own service
+- **Secure by Default**: Uses timing-safe comparison and one-time use tokens
+- **Flexible Storage**: Works with Rails.cache, Redis, or any custom cache store
+- **QR Code Generation**: Built-in support for generating QR codes for authenticator app setup
+- **Rails Generators**: Quick setup with `rails generate` commands
+- **Simple Configuration**: Minimal setup with sensible defaults
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rails_mfa'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install rails_mfa
+```
+
+## Quick Start
+
+### 1. Run the installer
+
+```bash
+rails generate rails_mfa:install
+```
+
+This creates an initializer at `config/initializers/rails_mfa.rb` with configuration options.
+
+### 2. Generate the migration
+
+```bash
+rails generate rails_mfa:migration User
+```
+
+This creates a migration to add MFA columns to your User model (or any model you specify).
+
+### 3. Run the migration
+
+```bash
+rails db:migrate
+```
+
+**Security Note**: The `mfa_secret` column should be encrypted in production. Use Rails 7's `encrypts` feature or `attr_encrypted`:
+
+```ruby
+class User < ApplicationRecord
+  encrypts :mfa_secret
+end
+```
+
+### 4. Include the Model concern in your User model
+
+```ruby
+class User < ApplicationRecord
+  include RailsMFA::Model
+
+  # Optional: specify which MFA methods this model supports
+  enable_mfa_for :sms, :email, :totp
+end
+```
+
+### 5. Configure Your Providers
+
+Edit `config/initializers/rails_mfa.rb` and configure your preferred SMS and email providers:
+
+```ruby
+RailsMFA.configure do |config|
+  # Use ANY SMS provider - Twilio, AWS SNS, Vonage, MessageBird, etc.
+  # Just provide a lambda that sends the SMS
+  config.sms_provider = lambda do |phone_number, message|
+    # Your SMS provider implementation here
+    # Example: YourSmsService.send(phone_number, message)
+  end
+
+  # Use ANY email provider - ActionMailer, SendGrid, Postmark, etc.
+  # Just provide a lambda that sends the email
+  config.email_provider = lambda do |email, subject, body|
+    # Your email provider implementation here
+    # Example: YourMailer.send_code(email, subject, body).deliver_now
+  end
+
+  # Optional: customize token settings
+  config.code_length = 6              # Default: 6 digits
+  config.code_expiry_seconds = 300    # Default: 5 minutes
+
+  # Optional: use custom cache store (Redis, Memcached, etc.)
+  # config.token_store = Redis.new
+end
+```
+
+## Usage
+
+### Email-based MFA
+
+```ruby
+# Send a verification code
+user = User.find(params[:id])
+code = user.send_numeric_code(via: :email)
+
+# Verify the code
+if user.verify_numeric_code(params[:code])
+  # Code is valid and user is authenticated
+  session[:mfa_verified] = true
+  redirect_to dashboard_path
+else
+  # Code is invalid
+  flash[:error] = "Invalid verification code"
+end
+```
+
+### SMS-based MFA
+
+```ruby
+# Send a verification code
+code = user.send_numeric_code(via: :sms)
+
+# Verify the code (same as email)
+if user.verify_numeric_code(params[:code])
+  session[:mfa_verified] = true
+  redirect_to dashboard_path
+end
+```
+
+### Authenticator App (TOTP) - Google Authenticator, Authy, 1Password, Microsoft Authenticator
+
+Authenticator apps provide the most secure MFA method using time-based one-time passwords (TOTP).
+
+#### Setup Flow
+
+```ruby
+# 1. Generate a secret for the user (do this once during setup)
+user.generate_totp_secret!
+
+# 2. Get the provisioning URI for QR code generation
+provisioning_uri = user.totp_provisioning_uri(issuer: "MyApp")
+
+# 3. Generate QR code for the user to scan
+require 'rqrcode'
+qrcode = RQRCode::QRCode.new(provisioning_uri)
+
+# For HTML view:
+@qr_svg = qrcode.as_svg(
+  module_size: 4,
+  standalone: true,
+  use_path: true
+)
+
+# Or for PNG:
+@qr_png = qrcode.as_png(size: 300)
+```
+
+#### Verification
+
+```ruby
+# Verify the TOTP code from the authenticator app
+if user.verify_totp(params[:code])
+  user.update(mfa_enabled: true, mfa_method: 'totp')
+  session[:mfa_verified] = true
+  redirect_to dashboard_path
+else
+  flash[:error] = "Invalid authenticator code"
+  render :verify
+end
+```
+
+#### Example Controller (Complete Setup Flow)
+
+```ruby
+# app/controllers/mfa/authenticator_controller.rb
+class Mfa::AuthenticatorController < ApplicationController
+  before_action :authenticate_user!
+
+  def new
+    # Show setup page
+  end
+
+  def create
+    # Generate secret and show QR code
+    current_user.generate_totp_secret!
+    provisioning_uri = current_user.totp_provisioning_uri(issuer: "MyApp")
+    @qrcode = RQRCode::QRCode.new(provisioning_uri)
+  end
+
+  def verify
+    # Verify the code from authenticator app
+    if current_user.verify_totp(params[:code])
+      current_user.update!(mfa_enabled: true, mfa_method: 'totp')
+      flash[:success] = "Authenticator app configured successfully!"
+      redirect_to profile_path
+    else
+      flash[:error] = "Invalid code. Please try again."
+      redirect_to mfa_authenticator_path
+    end
+  end
+end
+```
+
+#### Example View (QR Code Display)
+
+```erb
+<!-- app/views/mfa/authenticator/create.html.erb -->
+<div class="authenticator-setup">
+  <h2>Set Up Authenticator App</h2>
+
+  <p>Scan this QR code with your authenticator app:</p>
+
+  <div class="qr-code">
+    <%= @qrcode.as_svg(module_size: 4).html_safe %>
+  </div>
+
+  <p>Or enter this secret key manually:</p>
+  <code><%= current_user.mfa_secret %></code>
+
+  <p>After scanning, enter the 6-digit code from your app to verify:</p>
+
+  <%= form_with url: verify_mfa_authenticator_path, method: :post do |f| %>
+    <%= f.text_field :code, placeholder: "000000", maxlength: 6, autofocus: true %>
+    <%= f.submit "Verify and Enable" %>
+  <% end %>
+</div>
+```
+
+## Integration Examples
+
+### With Devise
+
+```ruby
+# app/controllers/users/mfa_controller.rb
+class Users::MfaController < ApplicationController
+  before_action :authenticate_user!
+
+  def show
+    # Display MFA setup page
+  end
+
+  def create
+    if current_user.verify_numeric_code(params[:code])
+      sign_in current_user, bypass: true
+      redirect_to root_path
+    else
+      flash[:alert] = "Invalid code"
+      redirect_to users_mfa_path
+    end
+  end
+
+  def send_code
+    current_user.send_numeric_code(via: params[:method].to_sym)
+    flash[:notice] = "Verification code sent"
+    redirect_to users_mfa_path
+  end
+end
+```
+
+Add routes:
+
+```ruby
+# config/routes.rb
+devise_for :users
+namespace :users do
+  resource :mfa, only: [:show, :create] do
+    post :send_code
+  end
+end
+```
+
+### With Custom Authentication
+
+```ruby
+# app/controllers/sessions_controller.rb
+class SessionsController < ApplicationController
+  def create
+    user = User.find_by(email: params[:email])
+
+    if user&.authenticate(params[:password])
+      if user.mfa_enabled?
+        # Store user ID in session temporarily
+        session[:pending_mfa_user_id] = user.id
+        user.send_numeric_code(via: :sms)
+        redirect_to mfa_verification_path
+      else
+        # No MFA required, log them in
+        session[:user_id] = user.id
+        redirect_to dashboard_path
+      end
+    else
+      flash[:error] = "Invalid credentials"
+      render :new
+    end
+  end
+end
+
+# app/controllers/mfa_verifications_controller.rb
+class MfaVerificationsController < ApplicationController
+  def show
+    # Display MFA verification form
+  end
+
+  def create
+    user = User.find(session[:pending_mfa_user_id])
+
+    if user.verify_numeric_code(params[:code])
+      session.delete(:pending_mfa_user_id)
+      session[:user_id] = user.id
+      redirect_to dashboard_path
+    else
+      flash[:error] = "Invalid verification code"
+      render :show
+    end
+  end
+end
+```
+
+## Provider Configuration Examples
+
+RailsMFA is **fully provider-agnostic**. You can use any SMS or email service by providing a simple lambda function. Here are examples for popular providers:
+
+### SMS Provider Examples
+
+#### Twilio
+
+```ruby
+# config/initializers/rails_mfa.rb
+RailsMFA.configure do |config|
+  config.sms_provider = lambda do |to, message|
+    require 'twilio-ruby'
+
+    client = Twilio::REST::Client.new(
+      ENV['TWILIO_ACCOUNT_SID'],
+      ENV['TWILIO_AUTH_TOKEN']
+    )
+
+    client.messages.create(
+      from: ENV['TWILIO_PHONE_NUMBER'],
+      to: to,
+      body: message
+    )
+  end
+end
+```
+
+#### AWS SNS
+
+```ruby
+# config/initializers/rails_mfa.rb
+RailsMFA.configure do |config|
+  config.sms_provider = lambda do |to, message|
+    require 'aws-sdk-sns'
+
+    sns = Aws::SNS::Client.new(
+      region: ENV['AWS_REGION'],
+      access_key_id: ENV['AWS_ACCESS_KEY_ID'],
+      secret_access_key: ENV['AWS_SECRET_ACCESS_KEY']
+    )
+
+    sns.publish(
+      phone_number: to,
+      message: message
+    )
+  end
+end
+```
+
+#### Vonage (Nexmo)
+
+```ruby
+RailsMFA.configure do |config|
+  config.sms_provider = lambda do |to, message|
+    require 'vonage'
+
+    client = Vonage::Client.new(
+      api_key: ENV['VONAGE_API_KEY'],
+      api_secret: ENV['VONAGE_API_SECRET']
+    )
+
+    client.sms.send(
+      from: ENV['VONAGE_PHONE_NUMBER'],
+      to: to,
+      text: message
+    )
+  end
+end
+```
+
+#### MessageBird
+
+```ruby
+RailsMFA.configure do |config|
+  config.sms_provider = lambda do |to, message|
+    require 'messagebird'
+
+    client = MessageBird::Client.new(ENV['MESSAGEBIRD_API_KEY'])
+
+    client.message_create(
+      ENV['MESSAGEBIRD_PHONE_NUMBER'],
+      to,
+      message
+    )
+  end
+end
+```
+
+#### Plivo
+
+```ruby
+RailsMFA.configure do |config|
+  config.sms_provider = lambda do |to, message|
+    require 'plivo'
+
+    client = Plivo::RestClient.new(
+      ENV['PLIVO_AUTH_ID'],
+      ENV['PLIVO_AUTH_TOKEN']
+    )
+
+    client.messages.create(
+      src: ENV['PLIVO_PHONE_NUMBER'],
+      dst: to,
+      text: message
+    )
+  end
+end
+```
+
+### Email Provider Examples
+
+#### SendGrid
+
+```ruby
+# config/initializers/rails_mfa.rb
+RailsMFA.configure do |config|
+  config.email_provider = lambda do |to, subject, body|
+    require 'sendgrid-ruby'
+    include SendGrid
+
+    from = Email.new(email: 'noreply@example.com')
+    to = Email.new(email: to)
+    content = Content.new(type: 'text/plain', value: body)
+    mail = Mail.new(from, subject, to, content)
+
+    sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])
+    sg.client.mail._('send').post(request_body: mail.to_json)
+  end
+end
+```
+
+### Custom ActionMailer Example
+
+```ruby
+# app/mailers/mfa_mailer.rb
+class MfaMailer < ApplicationMailer
+  def send_code(to, subject, body)
+    @code = body
+    mail(to: to, subject: subject)
+  end
+end
+
+# config/initializers/rails_mfa.rb
+RailsMFA.configure do |config|
+  config.email_provider = lambda do |to, subject, body|
+    MfaMailer.send_code(to, subject, body).deliver_now
+  end
+end
+```
+
+## Configuration Options
+
+```ruby
+RailsMFA.configure do |config|
+  # SMS provider (required for SMS-based MFA)
+  # Lambda that takes (phone_number, message) as arguments
+  config.sms_provider = ->(to, message) { ... }
+
+  # Email provider (required for email-based MFA)
+  # Lambda that takes (email, subject, body) as arguments
+  config.email_provider = ->(to, subject, body) { ... }
+
+  # Length of numeric codes (default: 6)
+  config.code_length = 6
+
+  # Code expiration time in seconds (default: 300 = 5 minutes)
+  config.code_expiry_seconds = 300
+
+  # Token storage backend (default: Rails.cache or SimpleStore)
+  config.token_store = Redis.new
+end
+```
+
+## Testing
+
+RailsMFA uses RSpec for testing. To run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+### Testing in Your Application
+
+You can stub the providers in your tests:
+
+```ruby
+RSpec.describe "MFA", type: :request do
+  before do
+    RailsMFA.configure do |config|
+      config.sms_provider = ->(to, message) { "SMS sent" }
+      config.email_provider = ->(to, subject, body) { "Email sent" }
+    end
+  end
+
+  it "sends verification code" do
+    user = create(:user)
+    post send_code_path, params: { method: 'sms' }
+
+    expect(response).to have_http_status(:success)
+  end
+end
+```
+
+## Security Considerations
+
+1. **Encrypt MFA Secrets**: Always encrypt the `mfa_secret` column in your database using Rails' built-in encryption or a gem like `attr_encrypted`.
+
+2. **HTTPS Only**: Always use HTTPS in production to prevent code interception.
+
+3. **Rate Limiting**: Implement rate limiting on MFA endpoints to prevent brute-force attacks:
+
+```ruby
+# Use rack-attack or similar
+throttle('mfa/verify', limit: 5, period: 5.minutes) do |req|
+  req.ip if req.path == '/mfa/verify' && req.post?
+end
+```
+
+4. **Secure Storage**: Use secure session storage (encrypted cookies or server-side sessions).
+
+5. **Backup Codes**: Consider implementing backup codes for account recovery.
+
+## Advanced Usage
+
+### Using with Redis
+
+```ruby
+# config/initializers/rails_mfa.rb
+RailsMFA.configure do |config|
+  config.token_store = Redis.new(
+    host: ENV['REDIS_HOST'],
+    port: ENV['REDIS_PORT'],
+    db: 1
+  )
+end
+```
+
+### Custom Token Length and Expiration
+
+```ruby
+# Generate an 8-digit code that expires in 10 minutes
+user.send_numeric_code(via: :email)
+
+# Configure globally
+RailsMFA.configure do |config|
+  config.code_length = 8
+  config.code_expiry_seconds = 600
+end
+```
+
+### Checking TOTP Status
+
+```ruby
+# Check if user has TOTP set up
+if user.mfa_secret.present? && user.mfa_enabled?
+  # User has TOTP configured
+end
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/shoaibmalik786/rails_mfa.
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Credits
+
+Created by [Shoaib Malik](https://github.com/shoaibmalik786)
+
+## Support
+
+If you have any questions or need help integrating RailsMFA, please open an issue on GitHub.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/rails_mfa/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsMFA
+  VERSION = "0.1.0"
+end

data/lib/rails_mfa.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "rails_mfa/version"
+require_relative "rails_mfa/configuration"
+require_relative "rails_mfa/token_manager"
+require_relative "rails_mfa/model"
+require_relative "rails_mfa/providers/base"
+require_relative "rails_mfa/providers/sms_provider"
+require_relative "rails_mfa/providers/email_provider"
+
+module RailsMFA
+  class Error < StandardError; end
+
+  class << self
+    attr_accessor :configuration
+
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration) if block_given?
+    end
+  end
+end

data/sig/rails_mfa.rbs

@@ -0,0 +1,4 @@
+module RailsMfa
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: rails_mfa
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Shoaib Malik
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-11-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: rotp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rqrcode
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+description: RailsMFA is a provider-agnostic, plug-and-play gem that adds secure multi-factor
+  authentication (MFA/2FA) to any Rails app. Supports SMS, email, and authenticator
+  apps (TOTP) with customizable providers.
+email:
+- shoaib2109@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/rails_mfa.rb
+- lib/rails_mfa/version.rb
+- sig/rails_mfa.rbs
+homepage: https://github.com/shoaibmalik786/rails_mfa
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/shoaibmalik786/rails_mfa
+  source_code_uri: https://github.com/shoaibmalik786/rails_mfa
+  changelog_uri: https://github.com/shoaibmalik786/rails_mfa/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Add multi-factor authentication (2FA/MFA) to any Rails app with pluggable
+  SMS, Email, and TOTP support.
+test_files: []