propel_authentication 0.1.1

data/lib/generators/propel_auth/templates/config/environments/development_email.rb

@@ -0,0 +1,43 @@
+# Email configuration for development environment
+# This file should be included in config/environments/development.rb
+
+# Configure Action Mailer for development
+config.action_mailer.delivery_method = :letter_opener
+config.action_mailer.perform_deliveries = true
+config.action_mailer.raise_delivery_errors = true
+config.action_mailer.default_options = { from: 'development@localhost' }
+
+# Configure Letter Opener to open emails in browser
+config.action_mailer.letter_opener_settings = {
+  location: Rails.root.join('tmp', 'letter_opener')
+}
+
+# URL options for email links
+config.action_mailer.default_url_options = { 
+  host: 'localhost', 
+  port: 3000,
+  protocol: 'http'
+}
+
+# Enable email previews
+config.action_mailer.show_previews = true
+config.action_mailer.preview_path = Rails.root.join('test', 'mailers', 'previews')
+
+# Log email delivery
+config.action_mailer.logger = Logger.new(STDOUT)
+config.action_mailer.log_level = :debug
+
+# SMTP settings for development (if you prefer real email delivery)
+# Uncomment and configure for services like Mailhog, MailCatcher, etc.
+# config.action_mailer.delivery_method = :smtp
+# config.action_mailer.smtp_settings = {
+#   address: 'localhost',
+#   port: 1025,
+#   domain: 'localhost',
+#   authentication: :plain,
+#   enable_starttls_auto: false
+# }
+
+puts "📧 Email development configuration loaded!"
+puts "🔧 Letter Opener will open emails in your browser"
+puts "👀 Email previews available at: http://localhost:3000/rails/mailers" 

data/lib/generators/propel_auth/templates/db/migrate/create_agencies.rb

@@ -0,0 +1,20 @@
+class CreateAgencies < ActiveRecord::Migration[8.0]
+  def change
+    create_table :agencies do |t|
+      t.string :name, null: false
+      t.references :organization, null: false, foreign_key: true
+      t.string :phone_number
+      t.string :address
+      t.string :time_zone
+      if ActiveRecord::Base.connection.adapter_name.downcase.starts_with?('postgresql')
+        t.jsonb :meta, default: {}
+        t.jsonb :settings, default: {}
+      else
+        t.json :meta, default: {}
+        t.json :settings, default: {}
+      end
+
+      t.timestamps
+    end
+  end
+end 

data/lib/generators/propel_auth/templates/db/migrate/create_agents.rb

@@ -0,0 +1,11 @@
+class CreateAgents < ActiveRecord::Migration[8.0]
+  def change
+    create_table :agents do |t|
+      t.references :user, null: false, foreign_key: true
+      t.references :agency, null: false, foreign_key: true
+      t.string :role, null: false, default: 'agent'
+      t.string :title
+      t.timestamps
+    end
+  end
+end 

data/lib/generators/propel_auth/templates/db/migrate/create_invitations.rb

@@ -0,0 +1,28 @@
+class CreateInvitations < ActiveRecord::Migration[8.0]
+  def change
+    create_table :invitations do |t|
+      # Multi-tenant associations
+      t.references :organization, null: false, foreign_key: true
+      t.references :inviter, null: false, foreign_key: { to_table: :users }
+      
+      # Rails 8 compatible email and user info fields
+      t.string :email_address, null: false
+      t.string :first_name, null: false
+      t.string :last_name, null: false
+      
+      # Invitation status tracking (enum: pending, accepted, expired, revoked)
+      t.integer :status, default: 0, null: false
+      
+      # Acceptance tracking
+      t.datetime :accepted_at
+      t.references :accepted_user, foreign_key: { to_table: :users }, null: true
+
+      t.timestamps
+    end
+    
+    # Indexes for performance and uniqueness
+    add_index :invitations, [:email_address, :organization_id], unique: true, name: 'index_invitations_on_email_and_org'
+    add_index :invitations, :status
+    add_index :invitations, :created_at
+  end
+end 

data/lib/generators/propel_auth/templates/db/migrate/create_organizations.rb

@@ -0,0 +1,18 @@
+class CreateOrganizations < ActiveRecord::Migration[8.0]
+  def change
+    create_table :organizations do |t|
+      t.string :name, null: false
+      t.string :website
+      t.string :time_zone
+      if ActiveRecord::Base.connection.adapter_name.downcase.starts_with?('postgresql')
+        t.jsonb :meta, default: {}
+        t.jsonb :settings, default: {}
+      else
+        t.json :meta, default: {}
+        t.json :settings, default: {}
+      end
+
+      t.timestamps
+    end
+  end
+end 

data/lib/generators/propel_auth/templates/db/migrate/create_users.rb

@@ -0,0 +1,43 @@
+class CreateUsers < ActiveRecord::Migration[8.0]
+  def change
+    create_table :users do |t|
+      t.string :email_address, null: false
+      t.string :username, null: false
+      t.string :phone_number
+      t.string :password_digest, null: false
+      
+      t.string :first_name
+      t.string :middle_name
+      t.string :last_name
+      t.string :time_zone
+
+      # Email confirmation fields
+      t.string :confirmation_token
+      t.datetime :confirmed_at
+      t.datetime :confirmation_sent_at
+      t.string :unconfirmed_email_address
+
+      t.integer :status, default: 0
+      t.datetime :last_login_at
+      t.integer :failed_login_attempts, default: 0
+      t.datetime :locked_at
+
+      # Multi-tenant association
+      t.references :organization, null: false, foreign_key: true
+
+      if ActiveRecord::Base.connection.adapter_name.downcase.starts_with?('postgresql')
+        t.jsonb :meta, default: {}
+        t.jsonb :settings, default: {}
+      else
+        t.json :meta, default: {}
+        t.json :settings, default: {}
+      end
+
+      t.timestamps
+    end
+    add_index :users, :email_address, unique: true
+    add_index :users, :username, unique: true
+    add_index :users, :phone_number, unique: true
+    add_index :users, :confirmation_token, unique: true
+  end
+end 

data/lib/generators/propel_auth/templates/db/seeds.rb

@@ -0,0 +1,29 @@
+# This file should ensure the existence of records required to run the application in every environment (production,
+# development, test). The code here should be idempotent so that it can be executed at any point in every environment.
+# The data can then be loaded with the bin/rails db:seed command (or created alongside the database with db:setup).
+#
+# Example:
+#
+#   ["Action", "Comedy", "Drama", "Horror"].each do |genre_name|
+#     MovieGenre.find_or_create_by!(name: genre_name)
+#   end
+
+# Create test organization and user for authentication testing
+organization = Organization.find_or_create_by!(name: 'Test Organization') do |org|
+  org.website = 'https://test.example.com'
+  org.time_zone = 'UTC'
+end
+
+user = User.find_or_create_by!(email_address: 'test@example.com') do |u|
+  u.username = 'testuser'
+  u.email_address = 'test@example.com'
+  u.password = 'password123'
+  u.password_confirmation = 'password123'
+  u.organization = organization
+  u.first_name = 'Test'
+  u.last_name = 'User'
+end
+
+puts "Created test organization: #{organization.name}"
+puts "Created test user: #{user.email_address} (password: password123)"
+puts "You can now test login with POST /auth/login"

data/lib/generators/propel_auth/templates/invitation.rb

@@ -0,0 +1,133 @@
+class Invitation < ApplicationRecord
+  # Multi-tenant associations
+  belongs_to :organization
+  belongs_to :inviter, class_name: 'User'
+
+  # Rails 8 compatible email field validation
+  validates :email_address, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+  validates :first_name, presence: true
+  validates :last_name, presence: true
+
+  # Status enum for invitation lifecycle - Rails 8 syntax
+  enum :status, { pending: 0, accepted: 1, expired: 2, revoked: 3 }
+
+  # Scopes for invitation management
+  scope :valid, -> { where(status: :pending).where('created_at > ?', 7.days.ago) }
+  scope :recent, -> { where('created_at > ?', 30.days.ago) }
+
+  # Check if invitation is still valid (not expired)
+  def invitation_valid?
+    pending? && created_at > 7.days.ago
+  end
+
+  # Check if invitation has expired
+  def expired?
+    !invitation_valid?
+  end
+
+  # Generate JWT-based invitation token
+  def generate_invitation_token
+    # Use high precision timestamp and organization context for uniqueness
+    now = Time.now
+    
+    payload = {
+      invitation_id: self.id,
+      email_address: self.email_address,
+      organization_id: self.organization_id,
+      inviter_id: self.inviter_id,
+      type: 'invitation',
+      iat: now.to_f,  # Use float for higher precision
+      exp: 7.days.from_now.to_i,  # 7 days expiration
+      # Bind token to invitation data to prevent tampering
+      invitation_hash: generate_invitation_hash
+    }
+    
+    JWT.encode(payload, PropelAuth.configuration.jwt_secret, 'HS256')
+  end
+
+  # Find invitation by JWT token with validation
+  def self.find_by_invitation_token(token)
+    begin
+      # Decode and validate the JWT token
+      payload = JWT.decode(token, PropelAuth.configuration.jwt_secret, true, { algorithm: 'HS256' })[0]
+      
+      # Verify this is an invitation token
+      return nil unless payload['type'] == 'invitation'
+      
+      # Find the invitation
+      invitation = find_by(id: payload['invitation_id'])
+      return nil unless invitation
+      
+      # Verify token matches this invitation
+      return nil unless payload['email_address'] == invitation.email_address
+      return nil unless payload['organization_id'] == invitation.organization_id
+      return nil unless payload['inviter_id'] == invitation.inviter_id
+      
+      # Verify invitation hash to prevent tampering
+      return nil unless payload['invitation_hash'] == invitation.generate_invitation_hash
+      
+      # Verify invitation is still valid
+      return nil unless invitation.invitation_valid?
+      
+      invitation
+    rescue JWT::DecodeError, JWT::ExpiredSignature, JWT::InvalidIssuerError
+      nil
+    end
+  end
+
+  # Accept invitation and create user account
+  def accept_with_user_params!(user_params)
+    return false unless invitation_valid?
+    
+    begin
+      # Create the user account
+      user = User.new(user_params.merge(
+        email_address: self.email_address,
+        first_name: self.first_name,
+        last_name: self.last_name,
+        organization: self.organization
+      ))
+      
+      if user.save
+        # Mark invitation as accepted
+        update!(status: :accepted)
+        
+        # Create agent relationship if needed
+        Agent.create!(
+          user: user,
+          agency: self.organization.agencies.first || self.organization.agencies.create!(name: 'Default Agency')
+        )
+        
+        user
+      else
+        false
+      end
+    rescue ActiveRecord::RecordInvalid
+      false
+    end
+  end
+
+  # Revoke invitation (admin action)
+  def revoke!
+    update!(status: :revoked)
+  end
+
+  # Get display name for invitee
+  def display_name
+    if first_name.present? && last_name.present?
+      "#{first_name} #{last_name}"
+    elsif first_name.present?
+      first_name
+    else
+      email_address.split('@').first.humanize
+    end
+  end
+
+  private
+
+  # Generate hash for invitation data to prevent token tampering
+  def generate_invitation_hash
+    data = "#{id}-#{email_address}-#{organization_id}-#{inviter_id}-#{created_at.to_i}"
+    Digest::SHA256.hexdigest(data)[0..10]  # First 11 characters for brevity
+  end
+end 

data/lib/generators/propel_auth/templates/lib/propel_auth.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module PropelAuth
+  # PropelAuth configuration and error classes
+  # This file was generated by PropelAuth and contains runtime functionality
+  # that was extracted from the gem to your application for customization.
+  
+  class Error < StandardError; end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = nil
+    end
+  end
+
+  class Configuration
+    attr_accessor :jwt_secret,
+                  :jwt_expiration,
+                  :jwt_algorithm,
+                  :password_length,
+                  :allow_registration,
+                  :require_email_confirmation,
+                  :confirmation_period,
+                  :confirmation_resend_interval,
+                  :max_failed_attempts,
+                  :lockout_duration,
+                  :password_reset_expiration,
+                  :password_reset_rate_limit,
+                  :frontend_url,
+                  :email_from_address,
+                  :support_email,
+                  :enable_email_notifications,
+                  :enable_sms_notifications,
+                  :api_version
+
+    def initialize
+      # JWT Configuration defaults
+      @jwt_secret = nil # Will be set in initializer
+      @jwt_expiration = 24.hours
+      @jwt_algorithm = 'HS256'
+      
+      # Password requirements
+      @password_length = 8..128
+      
+      # User registration settings
+      @allow_registration = true
+      
+      # Email confirmation settings
+      @require_email_confirmation = false
+      @confirmation_period = 24.hours       # How long confirmation tokens are valid
+      @confirmation_resend_interval = 1.minute # Minimum time between resend attempts
+      
+      # Account lockout settings
+      @max_failed_attempts = 10
+      @lockout_duration = 30.minutes
+      
+      # Password reset settings
+      @password_reset_expiration = 15.minutes
+      @password_reset_rate_limit = 1.minute
+      
+      # Frontend URL for email links (configure for your frontend application)
+      @frontend_url = Rails.env.development? ? 'http://localhost:3000' : nil
+      
+      # Email configuration
+      @email_from_address = "noreply@#{Rails.application.class.module_parent.name.downcase}.com"
+      @support_email = "support@#{Rails.application.class.module_parent.name.downcase}.com"
+      
+      # Notification preferences
+      @enable_email_notifications = true
+      @enable_sms_notifications = false # Requires SMS provider configuration
+      
+      # API versioning configuration
+      @api_version = 'v1'  # Default API version
+    end
+  end
+end 

data/lib/generators/propel_auth/templates/organization.rb

@@ -0,0 +1,7 @@
+class Organization < ApplicationRecord
+  # Multi-tenant associations
+  has_many :users, dependent: :destroy
+  has_many :agencies, dependent: :destroy
+
+  validates :name, presence: true
+end 

data/lib/generators/propel_auth/templates/propel_auth.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+# PropelAuth Configuration
+# This file was generated by: rails generate propel_auth:install
+# 
+# This module provides JWT-based authentication for Rails applications
+# with features like account lockout, password reset, and email confirmation.
+
+require "rails"
+
+module PropelAuth
+  class Error < StandardError; end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+
+  class Configuration
+    attr_accessor :jwt_secret,
+                  :jwt_expiration,
+                  :jwt_algorithm,
+                  :password_length,
+                  :allow_registration,
+                  :require_email_confirmation,
+                  :confirmation_period,
+                  :confirmation_resend_interval,
+                  :max_failed_attempts,
+                  :lockout_duration,
+                  :password_reset_expiration,
+                  :password_reset_rate_limit,
+                  :frontend_url,
+                  :email_from_address,
+                  :support_email,
+                  :enable_email_notifications,
+                  :enable_sms_notifications,
+                  :api_version
+
+    def initialize
+      # JWT Configuration defaults
+      @jwt_secret = nil # Will be set in configuration block
+      @jwt_expiration = 24.hours
+      @jwt_algorithm = 'HS256'
+      
+      # Password requirements
+      @password_length = 8..128
+      
+      # User registration settings
+      @allow_registration = true
+      
+      # Email confirmation settings
+      @require_email_confirmation = false
+      @confirmation_period = 24.hours       # How long confirmation tokens are valid
+      @confirmation_resend_interval = 1.minute # Minimum time between resend attempts
+      
+      # Account lockout settings
+      @max_failed_attempts = 10
+      @lockout_duration = 30.minutes
+      
+      # Password reset settings
+      @password_reset_expiration = 15.minutes
+      @password_reset_rate_limit = 1.minute
+      
+      # Frontend URL for email links (configure for your frontend application)
+      @frontend_url = Rails.env.development? ? 'http://localhost:3000' : nil
+      
+      # Email configuration
+      @email_from_address = "noreply@#{Rails.application.class.module_parent.name.downcase}.com"
+      @support_email = "support@#{Rails.application.class.module_parent.name.downcase}.com"
+      
+      # Notification preferences
+      @enable_email_notifications = true
+      @enable_sms_notifications = false # Requires SMS provider configuration
+      
+      # API versioning configuration
+      @api_version = 'v1'  # Default API version
+    end
+  end
+
+  class Engine < Rails::Engine
+    initializer 'propel_auth.load_generators' do |app|
+      config.generators do |g|
+        g.test_framework :minitest, fixture: true
+      end
+    end
+  end
+end
+
+# Configure PropelAuth with secure defaults
+PropelAuth.configure do |config|
+  # JWT Configuration for API authentication
+  config.jwt_secret = Rails.application.credentials.secret_key_base || ENV['SECRET_KEY_BASE'] || 'your-secret-key'
+  config.jwt_expiration = 24.hours
+  
+  # Password requirements
+  config.password_length = 8..128
+  
+  # User registration settings
+  config.allow_registration = true
+  
+  # Email confirmation (for future use)
+  config.require_email_confirmation = false
+  
+  # Account lockout settings
+  config.max_failed_attempts = 10
+  config.lockout_duration = 30.minutes
+  
+  # Password reset settings
+  config.password_reset_expiration = 15.minutes
+  config.password_reset_rate_limit = 1.minute
+  
+  # Environment-specific settings
+  if Rails.env.development?
+    # Development-specific settings
+    config.jwt_expiration = 24.hours
+  elsif Rails.env.production?
+    # Production-specific settings - shorter token expiration for security
+    config.jwt_expiration = 2.hours
+  end
+end
+
+# Note: Generator files are loaded from gem unless unpacked
+# To customize generators, run: rails generate propel_auth:unpack 

data/lib/generators/propel_auth/templates/services/auth_notification_service.rb

@@ -0,0 +1,89 @@
+class AuthNotificationService
+  class << self
+    def send_password_reset_email(user)
+      return false unless user&.persisted?
+      
+      begin
+        reset_token = user.generate_password_reset_token
+        reset_url = build_password_reset_url(reset_token)
+        
+        AuthMailer.with(
+          user: user,
+          token: reset_token,
+          reset_url: reset_url
+        ).password_reset.deliver_now
+        
+        { success: true, message: "Password reset email sent successfully" }
+      rescue StandardError => e
+        Rails.logger.error "Failed to send password reset email: #{e.message}"
+        { success: false, error: "Failed to send password reset email" }
+      end
+    end
+
+    def send_account_unlock_email(user)
+      return false unless user&.persisted? && user.locked?
+      
+      begin
+        unlock_token = user.generate_unlock_token
+        unlock_url = build_account_unlock_url(unlock_token)
+        
+        AuthMailer.with(
+          user: user,
+          token: unlock_token,
+          unlock_url: unlock_url
+        ).account_unlock.deliver_now
+        
+        { success: true, message: "Account unlock email sent successfully" }
+      rescue StandardError => e
+        Rails.logger.error "Failed to send account unlock email: #{e.message}"
+        { success: false, error: "Failed to send account unlock email" }
+      end
+    end
+
+    def send_user_invitation_email(invitation)
+      return false unless invitation&.persisted? && invitation.valid?
+      
+      begin
+        invitation_token = invitation.generate_invitation_token
+        invitation_url = build_invitation_url(invitation_token)
+        
+        AuthMailer.with(
+          invitation: invitation,
+          inviter: invitation.inviter,
+          token: invitation_token,
+          invitation_url: invitation_url
+        ).user_invitation.deliver_now
+        
+        { success: true, message: "Invitation email sent successfully" }
+      rescue StandardError => e
+        Rails.logger.error "Failed to send invitation email: #{e.message}"
+        { success: false, error: "Failed to send invitation email" }
+      end
+    end
+
+    private
+
+    def build_password_reset_url(token)
+      base_url = PropelAuth.configuration.frontend_url || default_frontend_url
+      "#{base_url}/reset-password?token=#{token}"
+    end
+
+    def build_account_unlock_url(token)
+      base_url = PropelAuth.configuration.frontend_url || default_frontend_url
+      "#{base_url}/unlock-account?token=#{token}"
+    end
+
+    def build_invitation_url(token)
+      base_url = PropelAuth.configuration.frontend_url || default_frontend_url
+      "#{base_url}/accept-invitation?token=#{token}"
+    end
+
+    def default_frontend_url
+      if Rails.env.development?
+        "http://localhost:3000"
+      else
+        "https://#{Rails.application.class.module_parent.name.downcase}.com"
+      end
+    end
+  end
+end