omniauth-identity 3.1.4 → 3.2.0

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

@@ -5,25 +5,73 @@ require "nobrainer"
 module OmniAuth
   module Identity
     module Models
-      # NoBrainer is an ORM adapter for RethinkDB:
-      #   http://nobrainer.io/
-      # NOTE: NoBrainer is based on ActiveModel.
+      # NoBrainer is an ORM adapter for RethinkDB: http://nobrainer.io/
+      #
+      # This module provides OmniAuth Identity functionality for NoBrainer models,
+      # including secure password handling and authentication key management.
+      #
+      # @example Usage
+      #   class User
+      #     include NoBrainer::Document
+      #
+      #     include OmniAuth::Identity::Models::NoBrainer
+      #
+      #     field :email
+      #     field :password_digest
+      #   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 NoBrainer is based on ActiveModel, so validations are enabled by default.
       module NoBrainer
-        def self.included(base)
-          base.class_eval do
-            include(::OmniAuth::Identity::Model)
-            include(::OmniAuth::Identity::SecurePassword)
+        class << self
+          # 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 included(base)
+            base.class_eval do
+              include(::OmniAuth::Identity::Model)
+              include(::OmniAuth::Identity::SecurePassword)
 
-            # validations: true (default) incurs a dependency on ActiveModel, but NoBrainer is ActiveModel based.
-            has_secure_password
+              # validations: true (default) incurs a dependency on ActiveModel, but NoBrainer is ActiveModel based.
+              has_secure_password
 
-            def self.auth_key=(key)
-              super
-              validates_uniqueness_of(key, case_sensitive: false)
-            end
+              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
+                #     include OmniAuth::Identity::Models::NoBrainer
+                #     self.auth_key = :email
+                #   end
+                def auth_key=(key)
+                  super
+                  validates_uniqueness_of(key, case_sensitive: false)
+                end
 
-            def self.locate(search_hash)
-              where(search_hash).first
+                # @!method self.locate(search_hash)
+                # Finds a record by the given search criteria.
+                #
+                # @param search_hash [Hash] the attributes to search for
+                # @return [Object, nil] the first matching record or nil
+                # @example
+                #   User.locate(email: 'user@example.com')
+                def locate(search_hash)
+                  where(search_hash).first
+                end
+              end
             end
           end
         end

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

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require "bcrypt"
+
+require "rom"
+require "rom-sql"
+
+module OmniAuth
+  module Identity
+    module Models
+      # ROM adapter for OmniAuth::Identity
+      # This provides a reusable adapter that makes ROM entities compatible with OmniAuth::Identity
+      #
+      # Usage:
+      #   class Identity
+      #     include OmniAuth::Identity::Models::Rom
+      #
+      #     # Configure the ROM container and relation using the DSL (no `self.`):
+      #     rom_container -> { MyDatabase.rom } # accepts a proc or a container object
+      #     rom_relation_name :identities # optional, defaults to :identities
+      #     owner_relation_name :owners  # optional, for loading associated owner
+      #     # Uses OmniAuth::Identity::Model.auth_key to set the auth key (defaults to :email)
+      #     auth_key :email
+      #     # Optional: override the password digest field name (defaults to :password_digest)
+      #     password_field :password_digest
+      #   end
+      module Rom
+        class << self
+          def included(base)
+            # Align with other adapters: rely on OmniAuth::Identity::Model for API
+            base.include(::OmniAuth::Identity::Model)
+            base.extend(ClassMethods)
+
+            base.class_eval do
+              # OmniAuth::Identity required instance API
+              # Authenticates the instance with the provided password
+              # Returns self on success, false otherwise (to match Model.authenticate contract)
+              define_method(:authenticate) do |password|
+                digest_key = self.class.password_field
+                password_digest = @identity_data[digest_key]
+                return false unless password_digest
+
+                begin
+                  BCrypt::Password.new(password_digest) == password && self
+                rescue BCrypt::Errors::InvalidHash
+                  false
+                end
+              end
+            end
+          end
+        end
+
+        module ClassMethods
+          # Default ROM relation name when none is configured
+          DEFAULT_RELATION_NAME = :identities
+
+          ROM_CONFIG_MUTEX = Mutex.new
+          private_constant :ROM_CONFIG_MUTEX
+
+          # Configuration DSL
+          # These methods act like the DSL on `OmniAuth::Identity::Model` (e.g. `auth_key`) —
+          # when called with an argument they set the configuration, and when called
+          # without an argument they return the current value (with sensible defaults).
+          def rom_container(value = false)
+            ROM_CONFIG_MUTEX.synchronize do
+              @rom_container = value unless value == false
+              container = @rom_container
+              container.respond_to?(:call) ? container.call : container
+            end
+          end
+
+          def rom_relation_name(value = false)
+            ROM_CONFIG_MUTEX.synchronize do
+              @rom_relation_name = value unless value == false
+              @rom_relation_name || DEFAULT_RELATION_NAME
+            end
+          end
+
+          def owner_relation_name(value = false)
+            ROM_CONFIG_MUTEX.synchronize do
+              @owner_relation_name = value unless value == false
+              @owner_relation_name
+            end
+          end
+
+          def password_field(value = false)
+            ROM_CONFIG_MUTEX.synchronize do
+              @password_field = value unless value == false
+              (@password_field || :password_digest).to_sym
+            end
+          end
+
+          # Align with other adapters: use Model.auth_key (getter/setter) for the login attribute
+          # Model.auth_key returns a String; convert to Symbol for ROM queries when needed.
+          def auth_key_symbol
+            (auth_key || "email").to_sym
+          end
+
+          # Locate an identity given conditions (Hash) or a raw key value.
+          # Mirrors other adapters by accepting a conditions hash.
+          # Returns an instance or nil.
+          def locate(conditions)
+            key_value = if conditions.is_a?(Hash)
+              conditions[auth_key_symbol] || conditions[auth_key.to_s]
+            else
+              conditions
+            end
+            return if key_value.nil?
+
+            relation = rom_container.relations[rom_relation_name]
+            identity_data = relation.where(auth_key_symbol => key_value).one
+            return unless identity_data
+
+            if owner_relation_name && identity_data[:owner_id]
+              owner_data = rom_container.relations[owner_relation_name].where(id: identity_data[:owner_id]).one
+              new(identity_data, owner_data)
+            else
+              new(identity_data)
+            end
+          end
+        end
+
+        # Instance shape matches other adapters for downstream usage
+        attr_reader :uid, :email, :name, :info, :owner
+
+        def initialize(identity_data, owner_data = nil)
+          @identity_data = identity_data
+          @owner_data = owner_data
+          @uid = identity_data[:id]
+          @email = identity_data[:email]
+
+          # Prefer owner name if available, else fall back to email
+          @name = if owner_data && owner_data[:name]
+            owner_data[:name]
+          else
+            identity_data[:email]
+          end
+
+          @info = {
+            "email" => @email,
+            "name" => @name,
+          }
+
+          @owner = owner_data
+        end
+
+        # Hash-like access to underlying ROM tuple
+        def [](key)
+          @identity_data[key]
+        end
+
+        # Convenience accessor for owner id
+        def owner_id
+          @identity_data[:owner_id]
+        end
+
+        # OmniAuth info hash
+        def to_hash
+          @info
+        end
+      end
+    end
+  end
+end

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

@@ -6,52 +6,116 @@ 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
-        def self.included(base)
-          base.class_eval do
-            # NOTE: Using the deprecated :validations_class_methods because it defines
-            #       validates_confirmation_of, while current :validation_helpers does not.
-            # plugin :validation_helpers
-            plugin(:validation_class_methods)
-
-            include(::OmniAuth::Identity::Model)
-            include(::OmniAuth::Identity::SecurePassword)
-
-            # `validations: true` (default) would normally incur a dependency on ActiveModel.
-            # Starting in v3.1 we check if ActiveModel is defined before we actually set validations.
-            # If ActiveModel isn't defined, it may be unexpected that validations are not being set,
-            #   so this will result in a warning deprecation until release of v4,
-            #   at which point the default (for Sequel ORM only) will change to `validations: false`
-            has_secure_password(validations: OmniAuth::Identity::Version.major < 4)
-
-            class << self
-              def auth_key=(key)
-                super
-                # Sequel version of validates_uniqueness_of! Does not incur ActiveRecord dependency!
-                validates_uniqueness_of(:key, case_sensitive: false)
-              end
+        # 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]
+        class << self
+          def included(base)
+            base.class_eval do
+              # NOTE: Using the deprecated :validations_class_methods because it defines
+              #       validates_confirmation_of, while current :validation_helpers does not.
+              # plugin :validation_helpers
+              plugin(:validation_class_methods)
+
+              include(::OmniAuth::Identity::Model)
+              include(::OmniAuth::Identity::SecurePassword)
+
+              # `validations: true` (default) would normally incur a dependency on ActiveModel.
+              # Starting in v3.1 we check if ActiveModel is defined before we actually set validations.
+              # If ActiveModel isn't defined, it may be unexpected that validations are not being set,
+              #   so this will result in a warning deprecation until release of v4,
+              #   at which point the default (for Sequel ORM only) will change to `validations: false`
+              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
-              def locate(arguments)
-                where(arguments).first
+                # @!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
-            end
 
-            def persisted?
-              exists?
-            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
 
-            def save
-              super
+              # @!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
             end
           end
         end

data/lib/omniauth/identity/secure_password.rb

@@ -9,21 +9,47 @@ 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
-      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
 
+      MIN_COST_MUTEX = Mutex.new
+      private_constant :MIN_COST_MUTEX
+
       class << self
-        attr_accessor :min_cost # :nodoc:
+        def included(base)
+          base.extend(ClassMethods) unless base.respond_to?(:has_secure_password)
+        end
+
+        # @!attribute [rw] min_cost
+        # Controls whether to use minimum cost for BCrypt hashing (for testing).
+        # @return [true, false]
+        def min_cost # :nodoc:
+          MIN_COST_MUTEX.synchronize { @min_cost.nil? ? false : @min_cost }
+        end
+
+        def min_cost=(value) # :nodoc:
+          MIN_COST_MUTEX.synchronize { @min_cost = value }
+        end
       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 +108,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 +151,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,17 @@
 # frozen_string_literal: true
 
-module OmniAuth
+module Omniauth
   module Identity
     module Version
-      VERSION = "3.1.4"
+      VERSION = "3.2.0"
     end
+    VERSION = Version::VERSION # Traditional Constant Location
+  end
+end
+
+module OmniAuth
+  module Identity
+    Version = Omniauth::Identity::Version unless const_defined?(:Version, false)
+    VERSION = Version::VERSION unless const_defined?(:VERSION, false)
   end
 end

data/lib/omniauth/identity.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 # TODO[v4]: Remove this deprecation with v4 release.
+require "version_gem"
+
 unless defined?(OmniAuth::Identity::Version::VERSION)
   # external gems
   require "version_gem"
@@ -18,20 +20,59 @@ 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
 end
+require_relative "identity/version"
+
+OmniAuth::Identity::Version.class_eval do
+  extend VersionGem::Basic
+end
+
+Omniauth::Identity::Version.class_eval do
+  extend VersionGem::Basic
+end