api_authentication_gem 0.1.3 → 0.4.0

data/lib/api_authentication_gem/auth.rb

@@ -0,0 +1,432 @@
+require "jwt"
+require "openssl"
+require "securerandom"
+
+module ApiAuthenticationGem
+  class Auth
+    # =========================================================================
+    # signup
+    # =========================================================================
+    # Success: { message:, user:, token:, refresh_token: (if enabled) }
+    # Failure: { error: }
+    def self.signup(email:, password:, ip_address: nil, user_agent: nil)
+      config = ApiAuthenticationGem.configuration
+
+      return { error: "Email is required" } if email.to_s.strip.empty?
+      return { error: "Password must be at least #{config.min_password_length} characters" } \
+        if password.to_s.length < config.min_password_length
+
+      user_class = config.user_class.constantize
+      user = user_class.new(
+        config.email_attribute    => email.to_s.strip.downcase,
+        config.password_attribute => password
+      )
+
+      if user.save
+        access_token = generate_access_token(user.id, ip_address: ip_address, user_agent: user_agent)
+        result = { message: "User created successfully", user: user, token: access_token }
+        result[:refresh_token] = generate_refresh_token_record(user.id).token if config.refresh_tokens_enabled
+        call_hook(:on_signup, user)
+        result
+      else
+        { error: user.errors.full_messages.join(", ") }
+      end
+    rescue ConfigurationError
+      raise
+    rescue StandardError => e
+      { error: e.message }
+    end
+
+    # =========================================================================
+    # login
+    # =========================================================================
+    # Success: { token:, user:, refresh_token: (if enabled) }
+    # Failure: { error: }
+    def self.login(email:, password:, ip_address: nil, user_agent: nil)
+      return { error: "Email and password are required" } \
+        if email.to_s.strip.empty? || password.to_s.strip.empty?
+
+      config     = ApiAuthenticationGem.configuration
+      normalized = email.to_s.strip.downcase
+
+      if config.lockout_enabled
+        lockout = Lockout.find_or_initialize_by(identifier: normalized)
+        return { error: "Account locked. Try again in #{lockout.minutes_remaining} minute(s)." } if lockout.locked?
+      end
+
+      user_class = config.user_class.constantize
+      user       = user_class.find_by(config.identifier => normalized)
+
+      if user.nil?
+        record_failed_attempt(normalized) if config.lockout_enabled
+        call_hook(:on_login_failure, normalized)
+        return { error: "Invalid email or password" }
+      end
+
+      unless user.respond_to?(config.password_verify_method)
+        raise ConfigurationError, "User model must respond to `#{config.password_verify_method}`"
+      end
+
+      unless user.public_send(config.password_verify_method, password)
+        record_failed_attempt(normalized) if config.lockout_enabled
+        call_hook(:on_login_failure, normalized)
+        return { error: "Invalid email or password" }
+      end
+
+      clear_lockout(normalized) if config.lockout_enabled
+
+      access_token = generate_access_token(user.id, ip_address: ip_address, user_agent: user_agent)
+      result       = { token: access_token, user: user }
+      result[:refresh_token] = generate_refresh_token_record(user.id).token if config.refresh_tokens_enabled
+      call_hook(:on_login, user)
+      result
+    rescue ConfigurationError
+      raise
+    rescue StandardError => e
+      { error: e.message }
+    end
+
+    # =========================================================================
+    # refresh
+    # =========================================================================
+    # Rotates tokens: revokes old refresh token, issues new access + refresh pair.
+    # Success: { token:, refresh_token:, user: }
+    # Failure: { error: }
+    def self.refresh(refresh_token:, ip_address: nil, user_agent: nil)
+      return { error: "Refresh token is required" } if refresh_token.to_s.strip.empty?
+
+      config = ApiAuthenticationGem.configuration
+      return { error: "Refresh tokens are not enabled" } unless config.refresh_tokens_enabled
+
+      record = RefreshToken.find_by(token: refresh_token)
+      return { error: "Invalid refresh token" }          unless record
+      return { error: "Refresh token has been revoked" } if     record.revoked_at
+      return { error: "Refresh token has expired" }      if     record.expires_at <= Time.now
+
+      record.revoke!
+
+      user_class = config.user_class.constantize
+      user       = user_class.find_by(id: record.user_id)
+      return { error: "User not found" } unless user
+
+      new_access  = generate_access_token(user.id, ip_address: ip_address, user_agent: user_agent)
+      new_refresh = generate_refresh_token_record(user.id)
+
+      { token: new_access, refresh_token: new_refresh.token, user: user }
+    rescue StandardError => e
+      { error: e.message }
+    end
+
+    # =========================================================================
+    # revoke
+    # =========================================================================
+    # Success: { message: }
+    # Failure: { error: }
+    def self.revoke(token:)
+      return { error: "Token is required" } if token.to_s.strip.empty?
+
+      config = ApiAuthenticationGem.configuration
+      return { error: "Token revocation is not enabled" } unless config.revocation_enabled
+
+      decoded = JWT.decode(token, verification_key, true, { algorithm: config.algorithm }).first
+
+      RevokedToken.find_or_create_by!(jti: decoded["jti"]) do |r|
+        r.expires_at = Time.at(decoded["exp"])
+      end
+
+      # Mirror into session tracker if enabled
+      AuthSession.find_by(jti: decoded["jti"])&.revoke! if config.session_tracking_enabled
+
+      call_hook(:on_logout, decoded["jti"])
+      { message: "Token revoked successfully" }
+    rescue JWT::ExpiredSignature
+      { error: "Cannot revoke an already-expired token" }
+    rescue JWT::DecodeError
+      { error: "Invalid token" }
+    rescue StandardError => e
+      { error: e.message }
+    end
+
+    # =========================================================================
+    # request_password_reset
+    # =========================================================================
+    def self.request_password_reset(email:)
+      return { error: "Email is required" } if email.to_s.strip.empty?
+
+      config     = ApiAuthenticationGem.configuration
+      normalized = email.to_s.strip.downcase
+      base_msg   = { message: "If that email is registered, a reset token has been sent." }
+
+      user_class = config.user_class.constantize
+      user       = user_class.find_by(config.identifier => normalized)
+      return base_msg unless user
+
+      PasswordReset.where(identifier: normalized, used_at: nil).update_all(used_at: Time.now)
+
+      reset = PasswordReset.create!(
+        identifier: normalized,
+        token:      SecureRandom.urlsafe_base64(32),
+        expires_at: Time.now + config.password_reset_expiry
+      )
+
+      base_msg.merge(reset_token: reset.token)
+    rescue StandardError => e
+      { error: e.message }
+    end
+
+    # =========================================================================
+    # reset_password
+    # =========================================================================
+    def self.reset_password(reset_token:, new_password:)
+      return { error: "Reset token is required" } if reset_token.to_s.strip.empty?
+
+      config = ApiAuthenticationGem.configuration
+
+      if new_password.to_s.length < config.min_password_length
+        return { error: "Password must be at least #{config.min_password_length} characters" }
+      end
+
+      record = PasswordReset.active.find_by(token: reset_token)
+      return { error: "Invalid or expired reset token" } unless record
+
+      user_class = config.user_class.constantize
+      user       = user_class.find_by(config.identifier => record.identifier)
+      return { error: "User not found" } unless user
+
+      if user.update(config.password_attribute => new_password)
+        record.consume!
+        call_hook(:on_password_reset, user)
+        { message: "Password has been reset successfully" }
+      else
+        { error: user.errors.full_messages.join(", ") }
+      end
+    rescue StandardError => e
+      { error: e.message }
+    end
+
+    # =========================================================================
+    # send_magic_link  (Tier 2)
+    # =========================================================================
+    # Generates a one-time login token the Rails app can email to the user.
+    # DO NOT expose magic_token directly in API responses.
+    # Success (known email):   { message:, magic_token: }
+    # Success (unknown email): { message: }
+    # Failure: { error: }
+    def self.send_magic_link(email:)
+      return { error: "Email is required" } if email.to_s.strip.empty?
+
+      config = ApiAuthenticationGem.configuration
+      return { error: "Magic link login is not enabled" } unless config.magic_link_enabled
+
+      normalized = email.to_s.strip.downcase
+      base_msg   = { message: "If that email is registered, a magic link has been sent." }
+
+      user_class = config.user_class.constantize
+      user       = user_class.find_by(config.identifier => normalized)
+      return base_msg unless user
+
+      # Invalidate any existing unused magic links for this email
+      MagicLink.where(identifier: normalized, used_at: nil).update_all(used_at: Time.now)
+
+      link = MagicLink.create!(
+        identifier: normalized,
+        token:      SecureRandom.urlsafe_base64(32),
+        expires_at: Time.now + config.magic_link_expiry
+      )
+
+      base_msg.merge(magic_token: link.token)
+    rescue StandardError => e
+      { error: e.message }
+    end
+
+    # =========================================================================
+    # verify_magic_link  (Tier 2)
+    # =========================================================================
+    # Validates the one-time token and returns a JWT — no password required.
+    # Success: { token:, user:, refresh_token: (if enabled) }
+    # Failure: { error: }
+    def self.verify_magic_link(token:, ip_address: nil, user_agent: nil)
+      return { error: "Magic link token is required" } if token.to_s.strip.empty?
+
+      config = ApiAuthenticationGem.configuration
+      return { error: "Magic link login is not enabled" } unless config.magic_link_enabled
+
+      link = MagicLink.active.find_by(token: token)
+      return { error: "Invalid or expired magic link" } unless link
+
+      user_class = config.user_class.constantize
+      user       = user_class.find_by(config.identifier => link.identifier)
+      return { error: "User not found" } unless user
+
+      link.consume!
+
+      access_token = generate_access_token(user.id, ip_address: ip_address, user_agent: user_agent)
+      result       = { token: access_token, user: user }
+      result[:refresh_token] = generate_refresh_token_record(user.id).token if config.refresh_tokens_enabled
+      call_hook(:on_login, user)
+      result
+    rescue StandardError => e
+      { error: e.message }
+    end
+
+    # =========================================================================
+    # active_sessions  (Tier 2)
+    # =========================================================================
+    # Returns all non-expired, non-revoked sessions for a user.
+    # Success: { sessions: [AuthSession, ...] }
+    # Failure: { error: }
+    def self.active_sessions(user_id:)
+      return { error: "Session tracking is not enabled" } \
+        unless ApiAuthenticationGem.configuration.session_tracking_enabled
+
+      { sessions: AuthSession.where(user_id: user_id).active.order(created_at: :desc) }
+    rescue StandardError => e
+      { error: e.message }
+    end
+
+    # =========================================================================
+    # revoke_session  (Tier 2)
+    # =========================================================================
+    # Revokes a specific session by jti; also adds to the revocation blocklist.
+    # Success: { message: }
+    # Failure: { error: }
+    def self.revoke_session(jti:)
+      config = ApiAuthenticationGem.configuration
+      return { error: "Session tracking is not enabled" } unless config.session_tracking_enabled
+      return { error: "JTI is required" } if jti.to_s.strip.empty?
+
+      session = AuthSession.find_by(jti: jti)
+      return { error: "Session not found" } unless session
+
+      session.revoke!
+
+      RevokedToken.find_or_create_by!(jti: jti) { |r| r.expires_at = session.expires_at } if config.revocation_enabled
+
+      call_hook(:on_logout, jti)
+      { message: "Session revoked successfully" }
+    rescue StandardError => e
+      { error: e.message }
+    end
+
+    # =========================================================================
+    # revoke_all_sessions  (Tier 2)
+    # =========================================================================
+    # Revokes every active session for a user — useful after password change or
+    # account compromise.
+    # Success: { message: "N session(s) revoked" }
+    # Failure: { error: }
+    def self.revoke_all_sessions(user_id:)
+      config = ApiAuthenticationGem.configuration
+      return { error: "Session tracking is not enabled" } unless config.session_tracking_enabled
+
+      sessions = AuthSession.where(user_id: user_id).active.to_a
+      sessions.each do |s|
+        s.revoke!
+        RevokedToken.find_or_create_by!(jti: s.jti) { |r| r.expires_at = s.expires_at } if config.revocation_enabled
+        call_hook(:on_logout, s.jti)
+      end
+
+      { message: "#{sessions.count} session(s) revoked" }
+    rescue StandardError => e
+      { error: e.message }
+    end
+
+    # =========================================================================
+    # decode
+    # =========================================================================
+    # Returns payload hash, or nil if invalid / expired / revoked.
+    def self.decode(token)
+      return nil if token.to_s.strip.empty?
+
+      config  = ApiAuthenticationGem.configuration
+      decoded = JWT.decode(
+        token,
+        verification_key,
+        true,
+        { algorithm: config.algorithm }
+      ).first
+
+      return nil if token_revoked?(decoded["jti"])
+
+      decoded
+    rescue JWT::ExpiredSignature, JWT::DecodeError
+      nil
+    end
+
+    # =========================================================================
+
+    # =========================================================================
+
+    def self.signing_key
+      config = ApiAuthenticationGem.configuration
+      config.algorithm == "RS256" ? config.private_key : config.secret_key
+    end
+
+    def self.verification_key
+      config = ApiAuthenticationGem.configuration
+      config.algorithm == "RS256" ? config.public_key : config.secret_key
+    end
+
+    def self.generate_access_token(user_id, ip_address: nil, user_agent: nil)
+      config = ApiAuthenticationGem.configuration
+      now    = Time.now.to_i
+      jti    = SecureRandom.uuid
+
+      payload = {
+        sub: user_id,
+        iat: now,
+        exp: now + config.token_expiry.to_i,
+        jti: jti
+      }
+
+      if config.session_tracking_enabled
+        AuthSession.create!(
+          user_id:    user_id,
+          jti:        jti,
+          ip_address: ip_address,
+          user_agent: user_agent,
+          expires_at: Time.at(payload[:exp])
+        )
+      end
+
+      JWT.encode(payload, signing_key, config.algorithm)
+    end
+
+    def self.generate_refresh_token_record(user_id)
+      config = ApiAuthenticationGem.configuration
+      RefreshToken.create!(
+        user_id:    user_id,
+        token:      SecureRandom.urlsafe_base64(32),
+        expires_at: Time.now + config.refresh_token_expiry.to_i
+      )
+    end
+
+    def self.token_revoked?(jti)
+      return false unless ApiAuthenticationGem.configuration.revocation_enabled
+
+      RevokedToken.revoked?(jti)
+    end
+
+    def self.record_failed_attempt(identifier)
+      config  = ApiAuthenticationGem.configuration
+      lockout = Lockout.find_or_initialize_by(identifier: identifier)
+      lockout.failed_attempts = (lockout.failed_attempts || 0) + 1
+      if lockout.failed_attempts >= config.max_login_attempts
+        lockout.locked_until    = Time.now + config.lockout_duration
+        lockout.failed_attempts = 0
+      end
+      lockout.save!
+    end
+
+    def self.clear_lockout(identifier)
+      Lockout.find_by(identifier: identifier)&.reset!
+    end
+
+    def self.call_hook(hook_name, *args)
+      hook = ApiAuthenticationGem.configuration.public_send(hook_name)
+      hook.call(*args) if hook.respond_to?(:call)
+    rescue StandardError => _e
+      # Hook errors must never interrupt the auth flow
+    end
+  end
+end

data/lib/api_authentication_gem/concerns/authenticatable.rb

@@ -0,0 +1,79 @@
+module ApiAuthenticationGem
+  module Concerns
+    module Authenticatable
+      def self.included(base)
+        base.helper_method :current_user if base.respond_to?(:helper_method)
+      end
+
+      # Decodes the Authorization header, sets @current_user.
+      # Renders 401 and returns false on any failure — the action never runs.
+      def authenticate_user!
+        token = extract_bearer_token
+        unless token
+          render json: { error: "Authorization token missing" }, status: :unauthorized
+          return false
+        end
+
+        decoded = ApiAuthenticationGem::Auth.decode(token)
+        unless decoded
+          render json: { error: "Invalid or expired token" }, status: :unauthorized
+          return false
+        end
+
+        user_id    = decoded["sub"] || decoded["user_id"]
+        user_class = ApiAuthenticationGem.configuration.user_class.constantize
+        @current_user = user_class.find_by(id: user_id)
+
+        unless @current_user
+          render json: { error: "User not found" }, status: :unauthorized
+          return false
+        end
+
+        true
+      end
+
+      # Role-based access control guard.
+      # Call after authenticate_user! has already set @current_user.
+      #
+      # Usage:
+      #   before_action -> { authorize_role!(:admin) }
+      #   before_action -> { authorize_role!(:admin, :moderator) }
+      #
+      # Returns true when allowed; renders 403 and returns false otherwise.
+      def authorize_role!(*allowed_roles)
+        unless current_user
+          render json: { error: "Not authenticated" }, status: :unauthorized
+          return false
+        end
+
+        config     = ApiAuthenticationGem.configuration
+        user_role  = current_user.public_send(config.role_attribute).to_s
+        allowed    = allowed_roles.map(&:to_s)
+
+        unless allowed.include?(user_role)
+          render json: {
+            error:    "Forbidden: insufficient permissions",
+            required: allowed,
+            current:  user_role
+          }, status: :forbidden
+          return false
+        end
+
+        true
+      end
+
+      def current_user
+        @current_user
+      end
+
+      private
+
+      def extract_bearer_token
+        header = request.headers["Authorization"]
+        return nil unless header.present?
+
+        header.start_with?("Bearer ") ? header.split(" ", 2).last.strip : header.strip
+      end
+    end
+  end
+end

data/lib/api_authentication_gem/configuration.rb

@@ -0,0 +1,114 @@
+module ApiAuthenticationGem
+  class Configuration
+    attr_accessor :secret_key,
+                  :user_class,
+                  :email_attribute,
+                  :password_attribute,
+                  :identifier,
+                  :password_verify_method,
+                  :token_expiry,
+                  :min_password_length,
+                  # --- Tier 1 ---
+                  :refresh_tokens_enabled,
+                  :refresh_token_expiry,
+                  :revocation_enabled,
+                  :password_reset_expiry,
+                  :lockout_enabled,
+                  :max_login_attempts,
+                  :lockout_duration,
+                  # --- Tier 2: RBAC ---
+                  :role_attribute,
+                  # --- Tier 2: Magic Link ---
+                  :magic_link_enabled,
+                  :magic_link_expiry,
+                  # --- Tier 2: Session Tracking ---
+                  :session_tracking_enabled,
+                  # --- Tier 2: Hooks ---
+                  :on_signup,
+                  :on_login,
+                  :on_login_failure,
+                  :on_logout,
+                  :on_password_reset,
+                  # --- Tier 2: Algorithm (HS256 or RS256) ---
+                  :algorithm,
+                  :private_key,
+                  :public_key
+
+    def initialize
+      # Core
+      @secret_key             = ENV.fetch("API_AUTH_SECRET_KEY", nil)
+      @user_class             = "User"
+      @email_attribute        = :email
+      @password_attribute     = :password
+      @identifier             = :email
+      @password_verify_method = :authenticate
+      @token_expiry           = 24 * 60 * 60
+      @min_password_length    = 6
+
+      # Tier 1
+      @refresh_tokens_enabled = false
+      @refresh_token_expiry   = 30 * 24 * 60 * 60
+      @revocation_enabled     = false
+      @password_reset_expiry  = 15 * 60
+      @lockout_enabled        = false
+      @max_login_attempts     = 5
+      @lockout_duration       = 15 * 60
+
+      # Tier 2: RBAC
+      @role_attribute         = :role
+
+      # Tier 2: Magic Link
+      @magic_link_enabled     = false
+      @magic_link_expiry      = 15 * 60
+
+      # Tier 2: Session Tracking
+      @session_tracking_enabled = false
+
+      # Tier 2: Hooks (nil = disabled)
+      @on_signup              = nil
+      @on_login               = nil
+      @on_login_failure       = nil
+      @on_logout              = nil
+      @on_password_reset      = nil
+
+      # Tier 2: Algorithm
+      @algorithm              = "HS256"
+      @private_key            = nil
+      @public_key             = nil
+    end
+
+    def validate!
+      if algorithm == "HS256"
+        if secret_key.nil? || secret_key.to_s.strip.empty?
+          raise ConfigurationError,
+                "secret_key must be set. Use ENV['API_AUTH_SECRET_KEY'] or set it explicitly."
+        end
+      elsif algorithm == "RS256"
+        raise ConfigurationError, "private_key must be an OpenSSL::PKey::RSA instance for RS256" \
+          unless private_key.is_a?(OpenSSL::PKey::RSA)
+        raise ConfigurationError, "public_key must be an OpenSSL::PKey::RSA instance for RS256" \
+          unless public_key.is_a?(OpenSSL::PKey::RSA)
+      else
+        raise ConfigurationError, "algorithm must be 'HS256' or 'RS256' (got '#{algorithm}')."
+      end
+
+      raise ConfigurationError, "token_expiry must be a positive integer (seconds)." if token_expiry.to_i <= 0
+      raise ConfigurationError, "min_password_length must be a positive integer." if min_password_length.to_i <= 0
+      if refresh_tokens_enabled && refresh_token_expiry.to_i <= 0
+        raise ConfigurationError, "refresh_token_expiry must be a positive integer (seconds)."
+      end
+      if lockout_enabled && max_login_attempts.to_i <= 0
+        raise ConfigurationError, "max_login_attempts must be a positive integer."
+      end
+      if lockout_enabled && lockout_duration.to_i <= 0
+        raise ConfigurationError, "lockout_duration must be a positive integer (seconds)."
+      end
+      if password_reset_expiry.to_i <= 0
+        raise ConfigurationError, "password_reset_expiry must be a positive integer (seconds)."
+      end
+      if magic_link_enabled && magic_link_expiry.to_i <= 0
+        raise ConfigurationError, "magic_link_expiry must be a positive integer (seconds)."
+      end
+    end
+  end
+end

data/lib/api_authentication_gem/errors.rb

@@ -0,0 +1,5 @@
+module ApiAuthenticationGem
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class AuthenticationError < Error; end
+end

data/lib/api_authentication_gem/models/auth_session.rb

@@ -0,0 +1,18 @@
+module ApiAuthenticationGem
+  class AuthSession < ::ActiveRecord::Base
+    self.table_name = "api_auth_sessions"
+
+    validates :user_id, :jti, :expires_at, presence: true
+    validates :jti, uniqueness: true
+
+    scope :active, -> { where(revoked_at: nil).where("expires_at > ?", Time.now) }
+
+    def active?
+      revoked_at.nil? && expires_at > Time.now
+    end
+
+    def revoke!
+      update!(revoked_at: Time.now)
+    end
+  end
+end

data/lib/api_authentication_gem/models/lockout.rb

@@ -0,0 +1,21 @@
+module ApiAuthenticationGem
+  class Lockout < ::ActiveRecord::Base
+    self.table_name = "api_auth_lockouts"
+
+    validates :identifier, presence: true, uniqueness: true
+
+    def locked?
+      locked_until.present? && locked_until > Time.now
+    end
+
+    def minutes_remaining
+      return 0 unless locked?
+
+      ((locked_until - Time.now) / 60).ceil
+    end
+
+    def reset!
+      update!(failed_attempts: 0, locked_until: nil)
+    end
+  end
+end

data/lib/api_authentication_gem/models/magic_link.rb

@@ -0,0 +1,22 @@
+module ApiAuthenticationGem
+  class MagicLink < ::ActiveRecord::Base
+    self.table_name = "api_auth_magic_links"
+
+    validates :identifier, :token, :expires_at, presence: true
+    validates :token, uniqueness: true
+
+    scope :active, -> { where(used_at: nil).where("expires_at > ?", Time.now) }
+
+    def expired?
+      expires_at <= Time.now
+    end
+
+    def used?
+      !used_at.nil?
+    end
+
+    def consume!
+      update!(used_at: Time.now)
+    end
+  end
+end