omniauth-identity 3.1.3 → 3.1.5

data/lib/omniauth/identity/models/sequel.rb

@@ -6,12 +6,41 @@ module OmniAuth
   module Identity
     module Models
       # Sequel is an ORM adapter for the following databases:
-      #   ADO, Amalgalite, IBM_DB, JDBC, MySQL, Mysql2, ODBC, Oracle, PostgreSQL, SQLAnywhere, SQLite3, and TinyTDS
+      # ADO, Amalgalite, IBM_DB, JDBC, MySQL, Mysql2, ODBC, Oracle, PostgreSQL, SQLAnywhere, SQLite3, and TinyTDS
       # The homepage is: http://sequel.jeremyevans.net/
-      # NOTE: Sequel is *not* based on ActiveModel, but supports the API we need, except for `persisted?`:
-      # * create
-      # * save
+      #
+      # This module provides OmniAuth Identity functionality for Sequel models,
+      # including secure password handling and authentication key management.
+      #
+      # @example Usage
+      #   class User < Sequel::Model(:users)
+      #     include OmniAuth::Identity::Models::Sequel
+      #   end
+      #
+      #   # Schema example:
+      #   # DB.create_table :users do
+      #   #   primary_key :id
+      #   #   String :email, null: false, unique: true
+      #   #   String :password_digest, null: false
+      #   # end
+      #
+      #   user = User.new(email: 'user@example.com', password: 'password')
+      #   user.save
+      #
+      #   # Authenticate a user
+      #   authenticated_user = User.locate(email: 'user@example.com')
+      #   authenticated_user.authenticate('password') # => user or false
+      #
+      # @note Sequel is *not* based on ActiveModel, but supports the API we need, except for `persisted?`.
+      # @note Validations are enabled by default in versions < 4, but may change to disabled in v4 if ActiveModel is not present.
       module Sequel
+        # Called when this module is included in a model class.
+        #
+        # This method extends the base class with OmniAuth Identity functionality,
+        # including secure password support and authentication key validation.
+        #
+        # @param base [Class] the model class including this module
+        # @return [void]
         def self.included(base)
           base.class_eval do
             # NOTE: Using the deprecated :validations_class_methods because it defines
@@ -30,26 +59,59 @@ module OmniAuth
             has_secure_password(validations: OmniAuth::Identity::Version.major < 4)
 
             class << self
+              # @!method self.auth_key=(key)
+              # Sets the authentication key for the model and adds uniqueness validation.
+              #
+              # @param key [Symbol, String] the attribute to use as the authentication key
+              # @return [void]
+              # @example
+              #   class User < Sequel::Model(:users)
+              #     include OmniAuth::Identity::Models::Sequel
+              #     self.auth_key = :email
+              #   end
               def auth_key=(key)
                 super
                 # Sequel version of validates_uniqueness_of! Does not incur ActiveRecord dependency!
                 validates_uniqueness_of(:key, case_sensitive: false)
               end
 
-              # @param arguments [any] -
-              #   Filtering is probably the most common dataset modifying action done in Sequel.
-              #   Both the where and filter methods filter the dataset by modifying the dataset’s WHERE clause.
-              #   Both accept a wide variety of input formats, which are passed as arguments below.
-              #   See: https://sequel.jeremyevans.net/rdoc/files/doc/querying_rdoc.html#label-Filters
+              # @!method self.locate(arguments)
+              # Finds a record by the given search criteria.
+              #
+              # Filtering is probably the most common dataset modifying action done in Sequel.
+              # Both the where and filter methods filter the dataset by modifying the dataset's WHERE clause.
+              # Both accept a wide variety of input formats.
+              # See: https://sequel.jeremyevans.net/rdoc/files/doc/querying_rdoc.html#label-Filters
+              #
+              # @param arguments [any] the search criteria
+              # @return [Sequel::Model, nil] the first matching record or nil
+              # @example
+              #   User.locate(email: 'user@example.com')
               def locate(arguments)
                 where(arguments).first
               end
             end
 
+            # @!method persisted?
+            # Checks if the record exists in the database.
+            #
+            # @return [Boolean] true if the record exists, false otherwise
+            # @example
+            #   user = User.new
+            #   user.persisted? # => false
+            #   user.save
+            #   user.persisted? # => true
             def persisted?
               exists?
             end
 
+            # @!method save
+            # Saves the record to the database.
+            #
+            # @return [Boolean] true if saved successfully, false otherwise
+            # @example
+            #   user = User.new(email: 'user@example.com', password: 'password')
+            #   user.save # => true
             def save
               super
             end

data/lib/omniauth/identity/secure_password.rb

@@ -9,21 +9,45 @@ module OmniAuth
     # include SecurePassword. The only difference is that instead of
     # using ActiveSupport::Concern, it checks to see if there is already
     # a has_secure_password method.
+    #
+    # Provides secure password hashing and authentication using BCrypt.
+    #
+    # @example Basic Usage
+    #   class User
+    #     include OmniAuth::Identity::SecurePassword
+    #
+    #     has_secure_password
+    #   end
+    #
+    #   user = User.new(password: 'secret')
+    #   user.authenticate('secret') # => user
     module SecurePassword
+      # Called when this module is included in a model class.
+      #
+      # Extends the base class with ClassMethods unless it already responds to has_secure_password.
+      #
+      # @param base [Class] the model class including this module
+      # @return [void]
       def self.included(base)
         base.extend(ClassMethods) unless base.respond_to?(:has_secure_password)
       end
 
+      # @!attribute [r] MAX_PASSWORD_LENGTH_ALLOWED
       # BCrypt hash function can handle maximum 72 bytes, and if we pass
       # password of length more than 72 bytes it ignores extra characters.
       # Hence need to put a restriction on password length.
+      # @return [Integer] The maximum allowed password length in bytes.
       MAX_PASSWORD_LENGTH_ALLOWED = BCrypt::Engine::MAX_SECRET_BYTESIZE
 
       class << self
+        # @!attribute [rw] min_cost
+        # Controls whether to use minimum cost for BCrypt hashing (for testing).
+        # @return [true, false]
         attr_accessor :min_cost # :nodoc:
       end
       self.min_cost = false
 
+      # Class-level methods for secure password functionality.
       module ClassMethods
         # Adds methods to set and authenticate against a BCrypt password.
         # This mechanism requires you to have a +XXX_digest+ attribute.
@@ -82,6 +106,10 @@ module OmniAuth
         #   user.authenticate_recovery_password('42password')          # => user
         #   User.find_by(name: 'david')&.authenticate('notright')      # => false
         #   User.find_by(name: 'david')&.authenticate('mUc3m00RsqyRe') # => user
+        #
+        # @param attribute [Symbol, String] the attribute name for the password (default: :password)
+        # @param validations [true, false] whether to add validations (default: true)
+        # @return [void]
         def has_secure_password(attribute = :password, validations: true)
           # Load bcrypt gem only when has_secure_password is used.
           # This is to avoid ActiveModel (and by extension the entire framework)
@@ -121,7 +149,12 @@ module OmniAuth
         end
       end
 
+      # A module that defines instance methods for password handling.
+      # Methods are defined dynamically based on the attribute name.
       class InstanceMethodsOnActivation < Module
+        # Initializes the module with the password attribute name.
+        #
+        # @param attribute [Symbol, String] the password attribute name
         def initialize(attribute)
           attr_reader(attribute)
 

data/lib/omniauth/identity/version.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
+# Contains version information for the OmniAuth Identity gem.
 module OmniAuth
   module Identity
     module Version
-      VERSION = "3.1.3"
+      # @!attribute [r] VERSION
+      # The current version of the omniauth-identity gem.
+      # @return [String]
+      VERSION = "3.1.5"
     end
   end
 end

data/lib/omniauth/identity.rb

@@ -18,19 +18,49 @@ end
 
 require "omniauth"
 
+# The main OmniAuth module.
 module OmniAuth
+  # Container for OmniAuth strategy classes.
   module Strategies
+    # Autoload the Identity strategy.
     autoload :Identity, "omniauth/strategies/identity"
   end
 
+  # OmniAuth Identity provides a way to authenticate users using a username and password
+  # stored in your application's database. It supports multiple ORMs and provides
+  # secure password hashing.
+  #
+  # @example Basic Setup
+  #   # In your Gemfile
+  #   gem 'omniauth-identity'
+  #
+  #   # In your OmniAuth configuration
+  #   use OmniAuth::Strategies::Identity,
+  #       fields: [:email],
+  #       model: User
+  #
+  # @see OmniAuth::Strategies::Identity
+  # @see OmniAuth::Identity::Model
+  # @see OmniAuth::Identity::SecurePassword
   module Identity
+    # Autoload the Model module.
     autoload :Model, "omniauth/identity/model"
+    # Autoload the SecurePassword module.
     autoload :SecurePassword, "omniauth/identity/secure_password"
+
+    # Container for ORM-specific model adapters.
     module Models
+      # Autoload the ActiveRecord adapter.
       autoload :ActiveRecord, "omniauth/identity/models/active_record"
+      # Autoload the Mongoid adapter.
       autoload :Mongoid, "omniauth/identity/models/mongoid"
+      # Autoload the CouchPotato adapter.
       autoload :CouchPotatoModule, "omniauth/identity/models/couch_potato"
+      # Autoload the NoBrainer adapter.
       autoload :NoBrainer, "omniauth/identity/models/nobrainer"
+      # Autoload the ROM adapter.
+      autoload :Rom, "omniauth/identity/models/rom"
+      # Autoload the Sequel adapter.
       autoload :Sequel, "omniauth/identity/models/sequel"
     end
   end

data/lib/omniauth/strategies/identity.rb

@@ -5,27 +5,96 @@ module OmniAuth
     # The identity strategy allows you to provide simple internal
     # user authentication using the same process flow that you
     # use for external OmniAuth providers.
+    #
+    # @example Basic Setup
+    #   use OmniAuth::Strategies::Identity,
+    #       fields: [:email],
+    #       model: User
+    #
+    # @example With Registration
+    #   use OmniAuth::Strategies::Identity,
+    #       fields: [:email, :name],
+    #       model: User,
+    #       enable_registration: true
+    #
+    # @see https://github.com/omniauth/omniauth-identity
     class Identity
+      # @!attribute [r] DEFAULT_REGISTRATION_FIELDS
+      # Default fields required for registration.
+      # @return [Array<Symbol>]
       DEFAULT_REGISTRATION_FIELDS = %i[password password_confirmation].freeze
       include OmniAuth::Strategy
+
+      # @!attribute [rw] fields
+      # The fields to collect for user registration.
+      # @return [Array<Symbol>]
       option :fields, %i[name email]
 
-      # Primary Feature Switches:
+      # @!attribute [rw] enable_registration
+      # Whether to enable user registration functionality.
+      # @return [true, false]
       option :enable_registration, true   # See #other_phase and #request_phase
+
+      # @!attribute [rw] enable_login
+      # Whether to enable login functionality.
+      # @return [true, false]
       option :enable_login, true          # See #other_phase
 
-      # Customization Options:
+      # @!attribute [rw] on_login
+      # Custom login handler. If provided, called instead of showing the default login form.
+      # @return [Proc, nil]
       option :on_login, nil               # See #request_phase
+
+      # @!attribute [rw] on_validation
+      # Custom validation handler for registration.
+      # @return [Proc, nil]
       option :on_validation, nil          # See #registration_phase
+
+      # @!attribute [rw] on_registration
+      # Custom registration handler. If provided, called instead of showing the default registration form.
+      # @return [Proc, nil]
       option :on_registration, nil        # See #registration_phase
+
+      # @!attribute [rw] on_failed_registration
+      # Custom handler for failed registration.
+      # @return [Proc, nil]
       option :on_failed_registration, nil # See #registration_phase
+
+      # @!attribute [rw] locate_conditions
+      # Conditions for locating an identity during login.
+      # @return [Proc, Hash]
       option :locate_conditions, ->(req) { {model.auth_key => req.params["auth_key"]} }
+
+      # @!attribute [rw] create_identity_link_text
+      # Text for the link to create a new identity.
+      # @return [String]
       option :create_identity_link_text, "Create an Identity"
+
+      # @!attribute [rw] registration_failure_message
+      # Message to display on registration failure.
+      # @return [String]
       option :registration_failure_message, "One or more fields were invalid"
+
+      # @!attribute [rw] validation_failure_message
+      # Message to display on validation failure.
+      # @return [String]
       option :validation_failure_message, "Validation failed"
+
+      # @!attribute [rw] title
+      # Title for the login form.
+      # @return [String]
       option :title, "Identity Verification" # Title for Login Form
+
+      # @!attribute [rw] registration_form_title
+      # Title for the registration form.
+      # @return [String]
       option :registration_form_title, "Register Identity" # Title for Registration Form
 
+      # Handles the initial request phase.
+      #
+      # Shows the login form or calls the custom on_login handler.
+      #
+      # @return [Rack::Response] the response to send
       def request_phase
         if options[:on_login]
           options[:on_login].call(env)
@@ -34,12 +103,22 @@ module OmniAuth
         end
       end
 
+      # Handles the callback phase after login.
+      #
+      # Authenticates the user and calls super if successful.
+      #
+      # @return [void]
       def callback_phase
         return fail!(:invalid_credentials) unless identity
 
         super
       end
 
+      # Handles other phases like registration.
+      #
+      # Routes to registration or login based on the path and options.
+      #
+      # @return [void]
       def other_phase
         if options[:enable_registration] && on_registration_path?
           if request.get?
@@ -61,6 +140,10 @@ module OmniAuth
         end
       end
 
+      # Shows the registration form or calls the custom on_registration handler.
+      #
+      # @param validation_message [String, nil] message to display if validation failed
+      # @return [Rack::Response] the response to send
       def registration_form(validation_message = nil)
         if options[:on_registration]
           options[:on_registration].call(env)
@@ -69,6 +152,11 @@ module OmniAuth
         end
       end
 
+      # Handles the registration phase.
+      #
+      # Creates a new identity and saves it.
+      #
+      # @return [void]
       def registration_phase
         attributes = (options[:fields] + DEFAULT_REGISTRATION_FIELDS).each_with_object({}) do |k, h|
           h[k] = request.params[k.to_s]
@@ -92,17 +180,33 @@ module OmniAuth
         end
       end
 
+      # @!method uid
+      # Returns the unique identifier for the authenticated identity.
+      # @return [String]
       uid { identity.uid }
+
+      # @!method info
+      # Returns the info hash for the authenticated identity.
+      # @return [Hash]
       info { identity.info }
 
+      # Returns the path for registration.
+      #
+      # @return [String] the registration path
       def registration_path
         options[:registration_path] || "#{script_name}#{path_prefix}/#{name}/register"
       end
 
+      # Checks if the current request is for the registration path.
+      #
+      # @return [true, false]
       def on_registration_path?
         on_path?(registration_path)
       end
 
+      # Finds and authenticates the identity based on the request parameters.
+      #
+      # @return [Object, nil] the authenticated identity or nil
       def identity
         conditions = options[:locate_conditions]
         conditions = conditions.is_a?(Proc) ? instance_exec(request, &conditions).to_hash : conditions.to_hash
@@ -110,12 +214,18 @@ module OmniAuth
         @identity ||= model.authenticate(conditions, request.params["password"])
       end
 
+      # Returns the model class to use for identities.
+      #
+      # @return [Class] the identity model class
       def model
         options[:model] || ::Identity
       end
 
       private
 
+      # Builds the login form.
+      #
+      # @return [OmniAuth::Form] the login form
       def build_omniauth_login_form
         OmniAuth::Form.build(
           title: options[:title],
@@ -129,6 +239,10 @@ module OmniAuth
         end
       end
 
+      # Builds the registration form.
+      #
+      # @param validation_message [String, nil] message to display
+      # @return [OmniAuth::Form] the registration form
       def build_omniauth_registration_form(validation_message)
         OmniAuth::Form.build(title: options[:registration_form_title]) do |f|
           f.html("<p style='color:red'>#{validation_message}</p>") if validation_message
@@ -140,22 +254,26 @@ module OmniAuth
         end
       end
 
-      # Validates the model before it is persisted
+      # Checks if validation is enabled.
       #
-      # @return [truthy or falsey] :on_validation option is truthy or falsey
+      # @return [true, false]
       def validating?
         !!options[:on_validation]
       end
 
-      # Validates the model before it is persisted
+      # Validates the identity using the custom validation handler.
       #
-      # @return [true or false] result of :on_validation call
+      # @return [true, false] result of validation
       def valid?
         # on_validation may run a Captcha or other validation mechanism
         # Must return true when validation passes, false otherwise
         !!options[:on_validation].call(env: env)
       end
 
+      # Handles registration failure.
+      #
+      # @param message [String] the failure message
+      # @return [void]
       def registration_failure(message)
         if options[:on_failed_registration]
           options[:on_failed_registration].call(env)
@@ -164,6 +282,9 @@ module OmniAuth
         end
       end
 
+      # Handles the result of registration.
+      #
+      # @return [void]
       def registration_result
         if @identity.persisted?
           env["PATH_INFO"] = "#{path_prefix}/#{name}/callback"