jwt_auth_engine 1.0.0

data/app/controllers/jwt_auth_engine/ping_controller.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module JwtAuthEngine
+  # Health check endpoints for public and authenticated connectivity.
+  class PingController < ApplicationController
+    skip_before_action :authenticate_auth_model!, only: %i[ping]
+
+    # GET /ping
+    # Public — no auth required
+    def ping
+      render_success(message: 'pong!')
+    end
+
+    # GET /authenticated_ping
+    # Protected — valid Bearer access token required
+    def authenticated_ping
+      recipient = current_auth_model_instance.public_send(JwtAuthEngine.identifier_field)
+      render_success(message: "pong! Hello #{recipient}, you are authenticated.")
+    end
+  end
+end

data/app/controllers/jwt_auth_engine/profiles_controller.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module JwtAuthEngine
+  # Profile retrieval endpoint for the authenticated auth model.
+  class ProfilesController < ApplicationController
+    include Serializable
+
+    # ── GET /me ───────────────────────────────────────────────────────────────
+    def me
+      render_success(
+        JwtAuthEngine.auth_model_name => serialize_auth_model_instance(current_auth_model_instance)
+      )
+    end
+  end
+end

data/app/controllers/jwt_auth_engine/registrations_controller.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module JwtAuthEngine
+  # Signup endpoint for creating new auth model records.
+  class RegistrationsController < ApplicationController
+    include Serializable
+    include Tokenizable
+
+    skip_before_action :authenticate_auth_model!, only: %i[signup]
+
+    # ── POST /signup ─────────────────────────────────────────────────────────
+    def signup
+      result = SignupService.new(signup_params: signup_params).call
+
+      return render_validation_error(errors: result[:errors]) unless result[:success]
+
+      auth_model_instance = result[JwtAuthEngine.auth_model_name]
+
+      render_success(
+        message: 'Signup successful.',
+        JwtAuthEngine.auth_model_name => serialize_auth_model_instance(auth_model_instance),
+        **issue_tokens(auth_model_instance),
+        status: :created
+      )
+    end
+
+    private
+
+    def signup_params
+      params.permit(JwtAuthEngine.identifier_field, JwtAuthEngine.password_field)
+    end
+  end
+end

data/app/controllers/jwt_auth_engine/sessions_controller.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module JwtAuthEngine
+  # Login and logout endpoints for session token lifecycle.
+  class SessionsController < ApplicationController
+    include Serializable
+    include Tokenizable
+
+    skip_before_action :authenticate_auth_model!, only: %i[login]
+
+    # ── POST /login ──────────────────────────────────────────────────────────
+    def login
+      result = LoginService.new(login_params: login_params).call
+
+      return render_unauthorized(result[:error]) unless result[:success]
+
+      auth_model_instance = result[JwtAuthEngine.auth_model_name]
+
+      render_success(
+        message: 'Login successful.',
+        JwtAuthEngine.auth_model_name => serialize_auth_model_instance(auth_model_instance),
+        **issue_tokens(auth_model_instance)
+      )
+    end
+
+    # ── DELETE /logout ─────────────────────────────────────────────────────────
+    # Stateless logout: the client should discard tokens.
+    def logout
+      render_success(status: :no_content)
+    end
+
+    private
+
+    def login_params
+      params.permit(
+        JwtAuthEngine.identifier_field,
+        JwtAuthEngine.password_field
+      )
+    end
+  end
+end

data/app/controllers/jwt_auth_engine/tokens_controller.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module JwtAuthEngine
+  # Endpoint for exchanging refresh tokens for a new token pair.
+  class TokensController < ApplicationController
+    include Tokenizable
+
+    skip_before_action :authenticate_auth_model!, only: %i[refresh_token]
+
+    # ── POST /refresh_token ───────────────────────────────────────────────────
+    # Verifies refresh JWT and re-issues a new token pair.
+    def refresh_token
+      result = RefreshTokenService.new(refresh_token: bearer_token).call
+      return render_unauthorized(result[:error]) unless result[:success]
+
+      auth_model_instance = result[JwtAuthEngine.auth_model_name]
+
+      render_success(**issue_tokens(auth_model_instance))
+    end
+  end
+end

data/app/services/jwt_auth_engine/base_service.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module JwtAuthEngine
+  # Base service with common success/failure response helpers.
+  class BaseService
+    def success(**data)
+      { success: true, **data }
+    end
+
+    def failure(**data)
+      { success: false, **data }
+    end
+
+    private
+
+    def authenticate(auth_model_instance, password)
+      return false if auth_model_instance.blank? || password.blank?
+
+      auth_model_instance.public_send(authentication_method, password)
+    end
+
+    def authentication_method
+      JwtAuthEngine.password_field == :password ? :authenticate : :"authenticate_#{JwtAuthEngine.password_field}"
+    end
+  end
+end

data/app/services/jwt_auth_engine/change_password_service.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module JwtAuthEngine
+  # Changes password for an authenticated auth model record.
+  class ChangePasswordService < BaseService
+    attr_reader :auth_model_instance, :current_password, :new_password
+
+    def initialize(auth_model_instance:, change_password_params:)
+      @auth_model_instance = auth_model_instance
+      @current_password = change_password_params[JwtAuthEngine.current_password_field]
+      @new_password = change_password_params[JwtAuthEngine.new_password_field]
+      super()
+    end
+
+    def call
+      return failure(invalid: required_fields_message) if missing_password_fields?
+      return failure(invalid: incorrect_password_message) unless current_password_valid?
+
+      update_password
+    end
+
+    private
+
+    def missing_password_fields?
+      current_password.blank? || new_password.blank?
+    end
+
+    def current_password_valid?
+      authenticate(auth_model_instance, current_password)
+    end
+
+    def update_password
+      if auth_model_instance.update(JwtAuthEngine.password_field => new_password.to_s)
+        success(message: 'Password changed successfully.')
+      else
+        failure(errors: auth_model_instance.errors.full_messages)
+      end
+    end
+
+    def required_fields_message
+      "#{JwtAuthEngine.current_password_field} and #{JwtAuthEngine.new_password_field} are required."
+    end
+
+    def incorrect_password_message
+      "Current #{JwtAuthEngine.password_field} is incorrect."
+    end
+  end
+end

data/app/services/jwt_auth_engine/login_service.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module JwtAuthEngine
+  # Authenticates identifier/password and returns the matched auth model.
+  class LoginService < BaseService
+    def initialize(login_params:)
+      @identifier = login_params[JwtAuthEngine.identifier_field]
+      @password = login_params[JwtAuthEngine.password_field]
+      super()
+    end
+
+    def call
+      if identifier.blank? || password.blank?
+        return failure(error: "#{JwtAuthEngine.identifier_field} and #{JwtAuthEngine.password_field} are required.")
+      end
+
+      auth_model_instance = find_auth_model_instance
+
+      if authenticate(auth_model_instance, password)
+        success(JwtAuthEngine.auth_model_name => auth_model_instance)
+      else
+        failure(error: 'Invalid credentials.')
+      end
+    end
+
+    private
+
+    attr_reader :identifier, :password
+
+    def find_auth_model_instance
+      model = JwtAuthEngine.auth_model_class
+
+      unless case_insensitive_identifier_field?(model)
+        return model.find_by(JwtAuthEngine.identifier_field => identifier)
+      end
+
+      identifier_column = model.connection.quote_column_name(JwtAuthEngine.identifier_field)
+      model.where("LOWER(#{identifier_column}) = ?", identifier.to_s.downcase).first
+    end
+
+    def case_insensitive_identifier_field?(model)
+      identifier_type = model.type_for_attribute(JwtAuthEngine.identifier_field.to_s).type
+      %i[string text].include?(identifier_type)
+    end
+  end
+end

data/app/services/jwt_auth_engine/refresh_token_service.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module JwtAuthEngine
+  # Validates refresh tokens and resolves the associated auth model.
+  class RefreshTokenService < BaseService
+    attr_reader :refresh_token
+
+    def initialize(refresh_token:)
+      @refresh_token = refresh_token
+      super()
+    end
+
+    def call
+      return failure(error: 'refresh_token is required.') if refresh_token.blank?
+
+      success(JwtAuthEngine.auth_model_name => auth_model_instance_from_token)
+    rescue JwtAuthEngine::TokenExpired
+      failure(error: 'Refresh token has expired.')
+    rescue JwtAuthEngine::InvalidToken
+      failure(error: 'Invalid refresh token.')
+    rescue JwtAuthEngine::InvalidTokenType
+      failure(error: 'Refresh token expected')
+    rescue ActiveRecord::RecordNotFound
+      failure(error: "#{JwtAuthEngine.auth_model_name.to_s.humanize} not found.")
+    end
+
+    private
+
+    def auth_model_instance_from_token
+      payload = TokenService.decode_refresh(refresh_token)
+      auth_model_id = payload[JwtAuthEngine.auth_model_token_payload_key]
+      JwtAuthEngine.auth_model_class.find(auth_model_id)
+    end
+  end
+end

data/app/services/jwt_auth_engine/signup_service.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module JwtAuthEngine
+  # Creates a new auth model record from signup parameters.
+  class SignupService < BaseService
+    attr_reader :signup_params
+
+    def initialize(signup_params:)
+      @signup_params = signup_params
+      super()
+    end
+
+    def call
+      auth_model_instance = JwtAuthEngine.auth_model_class.new(signup_params)
+
+      if auth_model_instance.save
+        success(JwtAuthEngine.auth_model_name => auth_model_instance)
+      else
+        failure(errors: auth_model_instance.errors.full_messages)
+      end
+    end
+  end
+end

data/app/services/jwt_auth_engine/token_service.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'jwt'
+
+module JwtAuthEngine
+  # Encodes and decodes JWT access/refresh tokens for the engine.
+  class TokenService
+    ACCESS_TYPE  = 'access'
+    REFRESH_TYPE = 'refresh'
+    ALGORITHM    = 'HS256'
+
+    class << self
+      # ── Encoding ─────────────────────────────────────────────────────────────
+
+      # Encodes an access token with the given payload. Automatically adds exp and token_type.
+      def encode_access(payload)
+        exp = JwtAuthEngine.configuration.access_token_expiry.from_now.to_i
+        encode(payload.merge(exp: exp, token_type: ACCESS_TYPE))
+      end
+
+      # Encodes a refresh token with the given payload. Automatically adds exp and token_type.
+      def encode_refresh(payload)
+        exp = JwtAuthEngine.configuration.refresh_token_expiry.from_now.to_i
+        encode(payload.merge(exp: exp, token_type: REFRESH_TYPE))
+      end
+
+      # ── Decoding ─────────────────────────────────────────────────────────────
+
+      # Decodes an access token. Raises on invalid/expired token.
+      def decode_access(token)
+        decode(token, expected_type: ACCESS_TYPE)
+      end
+
+      # Decodes a refresh token. Raises on invalid/expired token.
+      def decode_refresh(token)
+        decode(token, expected_type: REFRESH_TYPE)
+      end
+
+      # ── Private ──────────────────────────────────────────────────────────────
+
+      private
+
+      def encode(payload)
+        JWT.encode(payload, secret, ALGORITHM)
+      end
+
+      def decode(token, expected_type:)
+        decoded = JWT.decode(token, secret, true, { algorithm: ALGORITHM })
+        payload = HashWithIndifferentAccess.new(decoded[0])
+
+        validate_token_type!(payload, expected_type)
+
+        payload
+      rescue JWT::ExpiredSignature
+        raise JwtAuthEngine::TokenExpired, 'Token has expired'
+      rescue JWT::DecodeError => e
+        raise JwtAuthEngine::InvalidToken, "Invalid token: #{e.message}"
+      end
+
+      def validate_token_type!(payload, expected_type)
+        return if payload[:token_type] == expected_type
+
+        raise JwtAuthEngine::InvalidTokenType,
+              "Expected a #{expected_type} token but received #{payload[:token_type]}"
+      end
+
+      def secret
+        JwtAuthEngine.configuration.jwt_secret_key
+      end
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+JwtAuthEngine::Engine.routes.draw do
+  defaults format: :json do
+    # ── Ping endpoints ──────────────────────────────────────────────────────
+    controller :ping do
+      # GET /ping - public health check endpoint
+      get :ping
+
+      # GET /authenticated_ping - protected endpoint requiring valid access token
+      get :authenticated_ping
+    end
+
+    # ── Registration ─────────────────────────────────────────────────────────
+    controller :registrations do
+      # POST /signup - register a new account
+      post :signup
+    end
+
+    # ── Sessions ─────────────────────────────────────────────────────────────
+    controller :sessions do
+      # POST /login - authenticate and receive tokens
+      post :login
+
+      # DELETE /logout - stateless logout (client should discard tokens)
+      delete :logout
+    end
+
+    # ── Tokens ───────────────────────────────────────────────────────────────
+    controller :tokens do
+      # POST /refresh_token - exchange a valid refresh token for new tokens
+      post :refresh_token
+    end
+
+    # ── Passwords ────────────────────────────────────────────────────────────
+    controller :passwords do
+      # POST /change_password - change password for authenticated auth_model
+      post :change_password
+    end
+
+    # ── Profiles ─────────────────────────────────────────────────────────────
+    controller :profiles do
+      # GET /me - retrieve profile of authenticated auth_model
+      get :me
+    end
+  end
+end

data/lib/generators/jwt_auth_engine/install/install_generator.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module JwtAuthEngine
+  module Generators
+    # Generator that installs initializer, migration, and model concern wiring.
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      AUTH_MODEL_CONCERN_INCLUDE = 'include JwtAuthEngine::AuthModelConcern'
+
+      class_option :auth_model,
+                   type: :string, default: 'User', banner: 'User',
+                   desc: 'Auth model class name (e.g., User, Account, Admin::User)'
+
+      class_option :identifier_field,
+                   type: :string, default: 'email', banner: 'email',
+                   desc: 'Identifier field for login (e.g., email, username)'
+
+      class_option :password_field,
+                   type: :string, default: 'password', banner: 'password',
+                   desc: 'Password attribute name for has_secure_password'
+
+      def create_initializer
+        @auth_model = options[:auth_model]
+        @identifier_field = options[:identifier_field].to_sym
+        @password_field = options[:password_field].to_sym
+        template 'jwt_auth_engine_initializer.rb.tt', 'config/initializers/jwt_auth_engine.rb'
+      end
+
+      def copy_migration
+        @auth_model_table = options[:auth_model].tableize
+        @identifier_field = options[:identifier_field].to_sym
+        @password_digest_field = :"#{options[:password_field]}_digest"
+        @migration_class_name = "AddJwtAuthEngineColumnsTo#{@auth_model_table.classify.tr('::', '')}"
+        @migration_version = host_active_record_migration_version
+
+        migration_template(
+          'add_jwt_auth_engine_columns_migration.rb.tt',
+          "db/migrate/add_jwt_auth_engine_columns_to_#{@auth_model_table}.rb"
+        )
+      end
+
+      def create_auth_model_concern
+        template 'auth_model_concern.rb.tt', 'app/models/concerns/jwt_auth_engine/auth_model_concern.rb'
+      end
+
+      def inject_auth_model_concern
+        return warn_missing_auth_model_file unless File.exist?(auth_model_path)
+        return note_existing_auth_model_concern if auth_model_concern_included?
+
+        inject_into_class auth_model_path, options[:auth_model], "  #{AUTH_MODEL_CONCERN_INCLUDE}\n\n"
+      end
+
+      def self.next_migration_number(dirname)
+        if defined?(ActiveRecord::Generators::Base)
+          ActiveRecord::Generators::Base.next_migration_number(dirname)
+        else
+          Time.now.utc.strftime('%Y%m%d%H%M%S')
+        end
+      end
+
+      private
+
+      def auth_model_path
+        "app/models/#{options[:auth_model].underscore}.rb"
+      end
+
+      def warn_missing_auth_model_file
+        warning_message = "#{auth_model_path} not found. " \
+                          "Add `#{AUTH_MODEL_CONCERN_INCLUDE}` to #{options[:auth_model]} manually."
+        say_status :warning, warning_message, :yellow
+      end
+
+      def auth_model_concern_included?
+        File.read(auth_model_path).include?(AUTH_MODEL_CONCERN_INCLUDE)
+      end
+
+      def note_existing_auth_model_concern
+        message = "#{auth_model_path} already includes JwtAuthEngine::AuthModelConcern"
+        say_status :identical, message, :blue
+      end
+
+      def host_active_record_migration_version
+        return ActiveRecord::Migration.current_version if ActiveRecord::Migration.respond_to?(:current_version)
+
+        "#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}"
+      end
+    end
+  end
+end

data/lib/generators/jwt_auth_engine/install/templates/add_jwt_auth_engine_columns_migration.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class <%= @migration_class_name %> < ActiveRecord::Migration[<%= @migration_version %>]
+  def change
+    create_table :<%= @auth_model_table %>, if_not_exists: true, &:timestamps
+
+    add_column :<%= @auth_model_table %>, :<%= @identifier_field %>, :string, if_not_exists: true
+    add_column :<%= @auth_model_table %>, :<%= @password_digest_field %>, :string, if_not_exists: true
+    add_index :<%= @auth_model_table %>, :<%= @identifier_field %>, unique: true, if_not_exists: true
+  end
+end

data/lib/generators/jwt_auth_engine/install/templates/auth_model_concern.rb.tt

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module JwtAuthEngine
+  module AuthModelConcern
+    extend ActiveSupport::Concern
+
+    included do
+      has_secure_password JwtAuthEngine.password_field
+
+      validates JwtAuthEngine.identifier_field, presence: true, uniqueness: { case_sensitive: false }
+      validates JwtAuthEngine.password_field, length: { minimum: 8 }, allow_nil: true
+
+      # Generated default normalization for the configured identifier field.
+      # You can customize or remove this callback to match your identifier semantics.
+      before_validation :normalize_identifier
+    end
+
+    private
+
+    def normalize_identifier
+      field = JwtAuthEngine.identifier_field
+      reader = field.to_sym
+      writer = :"#{field}="
+      return unless respond_to?(reader) && respond_to?(writer)
+
+      value = public_send(reader)
+      return unless value.is_a?(String)
+
+      public_send(writer, value.strip.downcase)
+    end
+  end
+end

data/lib/generators/jwt_auth_engine/install/templates/jwt_auth_engine_initializer.rb.tt

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+JwtAuthEngine.configure do |config|
+  # Use your host application's auth model (e.g. User, Account, Admin::User)
+  config.auth_model = '<%= @auth_model %>'
+
+  # Field used by login/signup lookup. Most apps should keep :email.
+  config.identifier_field = :<%= @identifier_field %>
+
+  # Base password attribute used by has_secure_password.
+  # Digest column is derived as "#{password_field}_digest".
+  config.password_field = :<%= @password_field %>
+
+  # Required: set a secure secret key from your host app configuration.
+  # Example:
+  #   config.jwt_secret_key = Rails.application.credentials.dig(:jwt_auth_engine, :secret_key)
+  config.jwt_secret_key = nil
+
+  # Token expiry windows.
+  config.access_token_expiry = 8.hours
+  config.refresh_token_expiry = 7.days
+end

data/lib/jwt_auth_engine/configuration.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module JwtAuthEngine
+  # Runtime configuration container for auth model and token settings.
+  class Configuration
+    def initialize
+      @jwt_secret_key = nil
+      @auth_model = nil
+      @identifier_field = nil
+      @password_field = nil
+      @access_token_expiry = nil
+      @refresh_token_expiry = nil
+    end
+
+    attr_writer :jwt_secret_key,
+                :auth_model,
+                :identifier_field,
+                :password_field,
+                :access_token_expiry,
+                :refresh_token_expiry
+
+    def jwt_secret_key
+      @jwt_secret_key.presence || (
+        raise MissingSecretKey,
+              'Missing JWT secret key. ' \
+              "Set `config.#{JwtAuthEngine::Constants::JWT_SECRET_CONFIG_KEY}` in your initializer."
+      )
+    end
+
+    def auth_model
+      @auth_model.presence || Constants::DEFAULT_AUTH_MODEL
+    end
+
+    def identifier_field
+      @identifier_field.presence || Constants::DEFAULT_IDENTIFIER_FIELD
+    end
+
+    def password_field
+      @password_field.presence || Constants::DEFAULT_PASSWORD_FIELD
+    end
+
+    def access_token_expiry
+      @access_token_expiry.presence || Constants::DEFAULT_ACCESS_TOKEN_EXPIRY
+    end
+
+    def refresh_token_expiry
+      @refresh_token_expiry.presence || Constants::DEFAULT_REFRESH_TOKEN_EXPIRY
+    end
+  end
+end

data/lib/jwt_auth_engine/constants.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/integer/time'
+
+module JwtAuthEngine
+  module Constants
+    JWT_SECRET_CONFIG_KEY        = 'jwt_secret_key'
+
+    DEFAULT_AUTH_MODEL           = 'User'
+    DEFAULT_IDENTIFIER_FIELD     = :email
+    DEFAULT_PASSWORD_FIELD       = :password
+
+    DEFAULT_ACCESS_TOKEN_EXPIRY  = 8.hours
+    DEFAULT_REFRESH_TOKEN_EXPIRY = 7.days
+  end
+end