rsb-auth 0.9.1

data/lib/generators/rsb/auth/views/views_generator.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module RSB
+  module Auth
+    # Generator to export RSB Auth views to the host application for customization.
+    #
+    # Copies user-facing view files from the RSB Auth engine to the host app's
+    # `app/views/rsb/auth/` directory. Rails engine view lookup gives host app
+    # views priority over engine defaults, so copied views automatically override
+    # engine defaults without additional configuration.
+    #
+    # Admin views (identity management, sessions management) are NOT included —
+    # those are managed by the rsb-admin view generator.
+    #
+    # @example Export all auth views
+    #   rails generate rsb:auth:views
+    #
+    # @example Export only login and registration views
+    #   rails generate rsb:auth:views --only sessions,registrations
+    #
+    # @example Export mailer templates
+    #   rails generate rsb:auth:views --only mailers
+    #
+    # @example Force overwrite existing files
+    #   rails generate rsb:auth:views --force
+    #
+    class ViewsGenerator < Rails::Generators::Base
+      namespace 'rsb:auth:views'
+      desc 'Export RSB Auth views to your application for customization.'
+
+      class_option :only, type: :string, default: nil,
+                          desc: 'Comma-separated list of view groups to export (sessions,registrations,account,verifications,password_resets,invitations,mailers,layout)'
+      class_option :force, type: :boolean, default: false,
+                           desc: 'Overwrite existing files'
+
+      # Mapping of view groups to their file paths (relative to the engine views root).
+      # Each group corresponds to a controller's view directory.
+      # Admin views are intentionally excluded — use rsb:admin:views for those.
+      VIEW_GROUPS = {
+        'sessions' => [
+          'sessions/new.html.erb'
+        ],
+        'registrations' => [
+          'registrations/new.html.erb'
+        ],
+        'account' => [
+          'account/show.html.erb',
+          'account/confirm_destroy.html.erb',
+          'account/_identity_fields.html.erb'
+        ],
+        'verifications' => [
+          'verifications/show.html.erb'
+        ],
+        'password_resets' => [
+          'password_resets/new.html.erb',
+          'password_resets/edit.html.erb'
+        ],
+        'invitations' => [
+          'invitations/show.html.erb'
+        ],
+        'mailers' => [
+          'auth_mailer/verification.html.erb',
+          'auth_mailer/password_reset.html.erb',
+          'auth_mailer/invitation.html.erb'
+        ],
+        'layout' => [
+          'layouts/rsb/auth/application.html.erb'
+        ]
+      }.freeze
+
+      # Copies the selected view files from the engine to the host application.
+      #
+      # Iterates through the selected view groups and copies each file.
+      # Existing files are skipped unless --force is used.
+      #
+      # @return [void]
+      def copy_views
+        groups = selected_groups
+
+        files_copied = 0
+        files_skipped = 0
+
+        groups.each_value do |paths|
+          paths.each do |relative_path|
+            source = source_path_for(relative_path)
+            destination = destination_path_for(relative_path)
+
+            unless File.exist?(source)
+              say_status :skip, "#{relative_path} (not found in engine)", :yellow
+              next
+            end
+
+            if File.exist?(destination) && !options[:force]
+              say_status :skip, "#{relative_path} (already exists, use --force to overwrite)", :yellow
+              files_skipped += 1
+            else
+              copy_file_with_status(source, destination)
+              files_copied += 1
+            end
+          end
+        end
+
+        say ''
+        say "Exported #{files_copied} view(s) to app/views/rsb/auth/", :green
+        say "Skipped #{files_skipped} existing file(s)." if files_skipped.positive?
+      end
+
+      # Prints instructions about the view override chain.
+      #
+      # @return [void]
+      def print_instructions
+        say ''
+        say 'View override chain (highest priority first):', :cyan
+        say '  1. app/views/rsb/auth/ (your customizations)'
+        say '  2. RSB Auth engine defaults (fallback)'
+        say ''
+        say 'Edit the exported files to customize your auth pages.'
+        say "Files you didn't export will continue using engine defaults."
+        say ''
+      end
+
+      private
+
+      # Returns the filtered set of view groups based on the --only option.
+      #
+      # When --only is provided, parses the comma-separated list and validates
+      # that all group names are recognized. Returns only the matching groups.
+      # When --only is not provided, returns all groups.
+      #
+      # @return [Hash{String => Array<String>}] filtered view groups
+      # @raise [SystemExit] if invalid group names are provided
+      def selected_groups
+        if options[:only]
+          keys = options[:only].split(',').map(&:strip)
+          invalid = keys - VIEW_GROUPS.keys
+          if invalid.any?
+            say_status :error,
+                       "Unknown view group(s): #{invalid.join(', ')}. Valid groups: #{VIEW_GROUPS.keys.join(', ')}", :red
+            exit 1
+          end
+          VIEW_GROUPS.slice(*keys)
+        else
+          VIEW_GROUPS
+        end
+      end
+
+      # Returns the full source path for a given relative view path.
+      #
+      # Layout files live under app/views/layouts/ (not namespaced),
+      # while all other views live under app/views/rsb/auth/.
+      #
+      # @param relative_path [String] the relative path from VIEW_GROUPS
+      # @return [String] absolute path to the source file in the engine
+      def source_path_for(relative_path)
+        if relative_path.start_with?('layouts/')
+          RSB::Auth::Engine.root.join('app', 'views', relative_path).to_s
+        else
+          File.join(engine_views_root, relative_path)
+        end
+      end
+
+      # Returns the full destination path for a given relative view path.
+      #
+      # Layout files go to app/views/layouts/ (not namespaced),
+      # while all other views go to app/views/rsb/auth/.
+      #
+      # @param relative_path [String] the relative path from VIEW_GROUPS
+      # @return [String] absolute path to the destination file in the host app
+      def destination_path_for(relative_path)
+        if relative_path.start_with?('layouts/')
+          File.join(destination_root, 'app', 'views', relative_path)
+        else
+          File.join(destination_root, 'app', 'views', 'rsb', 'auth', relative_path)
+        end
+      end
+
+      # Returns the engine's namespaced views root directory.
+      #
+      # @return [String] absolute path to rsb/auth views in the engine
+      def engine_views_root
+        RSB::Auth::Engine.root.join('app', 'views', 'rsb', 'auth').to_s
+      end
+
+      # Copies a file and prints a create status message.
+      #
+      # @param source [String] absolute path to source file
+      # @param destination [String] absolute path to destination file
+      # @return [void]
+      def copy_file_with_status(source, destination)
+        FileUtils.mkdir_p(File.dirname(destination))
+        FileUtils.cp(source, destination)
+        relative = destination.sub("#{destination_root}/", '')
+        say_status :create, relative, :green
+      end
+    end
+  end
+end

data/lib/rsb/auth/configuration.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module RSB
+  module Auth
+    # Configuration for rsb-auth lifecycle handler and model concerns.
+    #
+    # @example Configure a custom handler and identity concerns
+    #   RSB::Auth.configure do |config|
+    #     config.lifecycle_handler = "MyApp::AuthLifecycleHandler"
+    #     config.identity_concerns << MyApp::HasProfile
+    #     config.credential_concerns << MyApp::HasTenant
+    #   end
+    #
+    class Configuration
+      # @return [String, nil] fully-qualified class name of the lifecycle handler.
+      #   When nil, the base {LifecycleHandler} null object is used.
+      attr_accessor :lifecycle_handler
+
+      # @return [Array<Module>] concern modules to include into Identity model.
+      #   Applied in order during Rails +to_prepare+ block.
+      attr_reader :identity_concerns
+
+      # @return [Array<Module>] concern modules to include into Credential base model.
+      #   Applied in order during Rails +to_prepare+ block. Inherited by all STI subtypes.
+      attr_reader :credential_concerns
+
+      # @return [Array<Symbol, Hash>] parameters permitted in account update form.
+      #   Default: +[:metadata]+. Host app extends this for concern-added nested attributes.
+      #
+      # @example Permit nested profile attributes
+      #   config.permitted_account_params = [:metadata, profile_attributes: [:first_name, :last_name]]
+      attr_accessor :permitted_account_params
+
+      def initialize
+        @lifecycle_handler = nil
+        @identity_concerns = []
+        @credential_concerns = []
+        @permitted_account_params = [:metadata]
+      end
+
+      # Resolves and instantiates the lifecycle handler.
+      #
+      # If {#lifecycle_handler} is set, constantizes the string and returns a new
+      # instance. If nil, returns a base {LifecycleHandler} (null object).
+      #
+      # The class name is resolved via +constantize+ on every call (not cached),
+      # which supports Rails code reloading in development.
+      #
+      # @return [RSB::Auth::LifecycleHandler] handler instance
+      def resolve_lifecycle_handler
+        if lifecycle_handler
+          lifecycle_handler.constantize.new
+        else
+          LifecycleHandler.new
+        end
+      end
+    end
+  end
+end

data/lib/rsb/auth/credential_conflict_error.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module RSB
+  module Auth
+    # Raised when restoring a revoked credential would violate the active
+    # uniqueness constraint (another active credential has the same type + identifier).
+    #
+    # @example Handling the error
+    #   begin
+    #     credential.restore!
+    #   rescue RSB::Auth::CredentialConflictError => e
+    #     e.message # => "Cannot restore — another active credential with the same identifier exists."
+    #   end
+    #
+    class CredentialConflictError < StandardError
+      def initialize(msg = 'Cannot restore — another active credential with the same identifier exists.')
+        super
+      end
+    end
+  end
+end

data/lib/rsb/auth/credential_definition.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module RSB
+  module Auth
+    class CredentialDefinition
+      attr_reader :key, :class_name, :authenticatable, :registerable, :label,
+                  :icon, :form_partial, :redirect_url, :admin_form_partial
+
+      # @param key [Symbol, String] unique identifier for the credential type
+      # @param class_name [String] fully-qualified class name of the credential model
+      # @param authenticatable [Boolean] whether this credential can be used to sign in (default: true)
+      # @param registerable [Boolean] whether new users can register with this credential (default: true)
+      # @param label [String, nil] human-readable label (defaults to titleized key)
+      # @param icon [String, nil] icon name for UI display (e.g. "mail", "phone", "user")
+      # @param form_partial [String, nil] Rails partial path for the credential's login/register form
+      # @param redirect_url [String, nil] redirect URL for OAuth/redirect-based credential flows
+      def initialize(key:, class_name:, authenticatable: true, registerable: true, label: nil,
+                     icon: nil, form_partial: nil, redirect_url: nil, admin_form_partial: nil)
+        @key = key.to_sym
+        @class_name = class_name.to_s
+        @authenticatable = authenticatable
+        @registerable = registerable
+        @label = label || key.to_s.titleize
+        @icon = icon
+        @form_partial = form_partial
+        @redirect_url = redirect_url
+        @admin_form_partial = admin_form_partial
+      end
+
+      def credential_class
+        @class_name.constantize
+      end
+
+      def valid?
+        key.present? && class_name.present?
+      end
+    end
+  end
+end

data/lib/rsb/auth/credential_deprecation_bridge.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module RSB
+  module Auth
+    # Provides backward compatibility between the old `auth.login_identifier`
+    # setting and the new per-credential `auth.credentials.<key>.enabled` settings.
+    #
+    # When per-credential settings are NOT explicitly set in the database,
+    # this bridge reads `auth.login_identifier` and infers which types should
+    # be enabled. When per-credential settings ARE explicitly set, this bridge
+    # is bypassed entirely — the explicit settings win.
+    #
+    # @see SRS-004 US-006 (Deprecate login_identifier)
+    class CredentialDeprecationBridge
+      IDENTIFIER_MAP = {
+        'email' => { email_password: true, phone_password: false, username_password: false },
+        'phone' => { email_password: false, phone_password: true, username_password: false },
+        'username' => { email_password: false, phone_password: false, username_password: true }
+      }.freeze
+
+      class << self
+        # Returns the enabled/disabled map for a given login_identifier value.
+        #
+        # @param identifier [String] "email", "phone", or "username"
+        # @return [Hash<Symbol, Boolean>]
+        def enabled_map_for(identifier)
+          IDENTIFIER_MAP.fetch(identifier.to_s, IDENTIFIER_MAP['email'])
+        end
+
+        # Checks whether any per-credential enabled setting has been explicitly
+        # set in the database (not just relying on the default).
+        #
+        # @return [Boolean]
+        def per_credential_settings_explicit?
+          RSB::Auth.credentials.all.any? do |defn|
+            RSB::Settings::Setting.exists?(
+              category: 'auth',
+              key: "credentials.#{defn.key}.enabled"
+            )
+          end
+        rescue StandardError
+          false
+        end
+
+        # Resolves the deprecated login_identifier into per-credential settings.
+        # Only called when per-credential settings are NOT explicitly set.
+        # Logs a deprecation warning.
+        #
+        # @return [void]
+        def resolve_from_login_identifier
+          identifier = RSB::Settings.get('auth.login_identifier')
+          fire_deprecation(
+            'auth.login_identifier is deprecated. Use auth.credentials.<key>.enabled settings instead. ' \
+            "Current value '#{identifier}' maps to: #{enabled_map_for(identifier).inspect}"
+          )
+        end
+
+        # Register a deprecation handler (for testing).
+        # @param block [Proc]
+        def on_deprecation(&block)
+          @deprecation_handler = block
+        end
+
+        # Clear the deprecation handler (for test teardown).
+        def clear_deprecation_handler
+          @deprecation_handler = nil
+        end
+
+        private
+
+        def fire_deprecation(message)
+          if @deprecation_handler
+            @deprecation_handler.call(message)
+          elsif defined?(Rails) && Rails.logger
+            Rails.logger.warn("[RSB::Auth DEPRECATION] #{message}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rsb/auth/credential_registry.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module RSB
+  module Auth
+    class CredentialRegistry
+      attr_reader :definitions
+
+      def initialize
+        @definitions = {}
+      end
+
+      def register(definition)
+        unless definition.is_a?(CredentialDefinition)
+          raise ArgumentError, "Expected CredentialDefinition, got #{definition.class}"
+        end
+
+        @definitions[definition.key] = definition
+      end
+
+      def find(key)
+        @definitions[key.to_sym]
+      end
+
+      def all
+        @definitions.values
+      end
+
+      def authenticatable
+        @definitions.values.select(&:authenticatable)
+      end
+
+      def registerable
+        @definitions.values.select(&:registerable)
+      end
+
+      def for_identifier(identifier_type)
+        # Find the default credential type for a given login identifier
+        key = :"#{identifier_type}_password"
+        @definitions[key]
+      end
+
+      def keys
+        @definitions.keys
+      end
+
+      # Returns only credential definitions that are currently enabled via settings.
+      # A credential type is enabled if `auth.credentials.<key>.enabled` resolves to `true`.
+      # If no setting exists for the credential type, it defaults to enabled (true).
+      #
+      # @return [Array<CredentialDefinition>]
+      def enabled
+        @definitions.values.select { |defn| credential_enabled?(defn.key) }
+      end
+
+      # Returns keys of enabled credential types.
+      #
+      # @return [Array<Symbol>]
+      def enabled_keys
+        enabled.map(&:key)
+      end
+
+      # Checks if a specific credential type is enabled.
+      # Returns false if the credential type is not registered.
+      #
+      # @param key [Symbol, String] credential type key
+      # @return [Boolean]
+      def enabled?(key)
+        defn = @definitions[key.to_sym]
+        return false unless defn
+
+        credential_enabled?(defn.key)
+      end
+
+      private
+
+      # Reads the enabled setting for a credential type.
+      # Falls back to true if no setting is registered (backward compat / custom types
+      # that haven't registered their enabled setting yet).
+      #
+      # @param key [Symbol] credential type key
+      # @return [Boolean]
+      def credential_enabled?(key)
+        setting_key = "auth.credentials.#{key}.enabled"
+        value = begin
+          RSB::Settings.get(setting_key)
+        rescue StandardError
+          nil
+        end
+        # If no setting registered, default to true (backward compat)
+        return true if value.nil?
+
+        ActiveModel::Type::Boolean.new.cast(value)
+      end
+    end
+  end
+end

data/lib/rsb/auth/credential_settings_registrar.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module RSB
+  module Auth
+    # Handles registration of per-credential-type enabled settings
+    # and validation callbacks (e.g., preventing disabling the last type).
+    #
+    # Called from the engine initializer after credential types are registered.
+    class CredentialSettingsRegistrar
+      # Auto-registers `auth.credentials.<key>.enabled` settings for all
+      # currently registered credential types.
+      #
+      # @return [void]
+      def self.register_enabled_settings
+        definitions = RSB::Auth.credentials.all
+        return if definitions.empty?
+
+        schema = RSB::Settings::Schema.new('auth') do
+          definitions.each do |defn|
+            setting :"credentials.#{defn.key}.enabled",
+                    type: :boolean,
+                    default: true,
+                    group: 'Credential Types',
+                    label: defn.label,
+                    description: "Enable or disable #{defn.label} as a sign-in method"
+
+            setting :"credentials.#{defn.key}.verification_required",
+                    type: :boolean,
+                    default: true,
+                    group: 'Credential Types',
+                    label: "#{defn.label} — Verification Required",
+                    depends_on: "auth.credentials.#{defn.key}.enabled",
+                    description: "Require email verification before login for #{defn.label}"
+
+            setting :"credentials.#{defn.key}.auto_verify_on_signup",
+                    type: :boolean,
+                    default: false,
+                    group: 'Credential Types',
+                    label: "#{defn.label} — Auto-verify on Signup",
+                    depends_on: "auth.credentials.#{defn.key}.enabled",
+                    description: "Auto-verify credentials at registration time for #{defn.label}"
+
+            setting :"credentials.#{defn.key}.allow_login_unverified",
+                    type: :boolean,
+                    default: false,
+                    group: 'Credential Types',
+                    label: "#{defn.label} — Allow Login Unverified",
+                    depends_on: "auth.credentials.#{defn.key}.enabled",
+                    description: "Allow login without verification for #{defn.label}"
+
+            setting :"credentials.#{defn.key}.registerable",
+                    type: :boolean,
+                    default: true,
+                    group: 'Credential Types',
+                    label: "#{defn.label} — Self-registration",
+                    depends_on: "auth.credentials.#{defn.key}.enabled",
+                    description: "Allow self-registration for #{defn.label}"
+          end
+        end
+
+        RSB::Settings.registry.register(schema)
+      end
+
+      # Registers on_change callbacks that prevent disabling the last
+      # enabled credential type. For each credential type, when its
+      # enabled setting changes to false, check that at least one other
+      # type remains enabled.
+      #
+      # @return [void]
+      def self.register_last_type_validation
+        RSB::Auth.credentials.all.each do |defn|
+          setting_key = "auth.credentials.#{defn.key}.enabled"
+          RSB::Settings.registry.on_change(setting_key) do |_old_value, new_value|
+            # Only check when disabling (new_value is falsy)
+            is_disabling = !ActiveModel::Type::Boolean.new.cast(new_value)
+            if is_disabling
+              # Count how many OTHER types are still enabled
+              other_enabled = RSB::Auth.credentials.all.count do |other|
+                next false if other.key == defn.key
+
+                RSB::Auth.credentials.enabled?(other.key)
+              end
+
+              if other_enabled.zero?
+                raise RSB::Settings::ValidationError,
+                      "Cannot disable #{defn.label}: at least one credential type must remain enabled."
+              end
+            end
+          end
+
+          # Mutual exclusion: auto_verify_on_signup and verification_required cannot both be true
+          auto_verify_key = "auth.credentials.#{defn.key}.auto_verify_on_signup"
+          verification_key = "auth.credentials.#{defn.key}.verification_required"
+
+          RSB::Settings.registry.on_change(auto_verify_key) do |_old_value, new_value|
+            if ActiveModel::Type::Boolean.new.cast(new_value)
+              verif = RSB::Settings.get(verification_key)
+              if ActiveModel::Type::Boolean.new.cast(verif)
+                raise RSB::Settings::ValidationError,
+                      "Cannot enable auto-verify when verification is required for #{defn.label}. Disable verification_required first."
+              end
+            end
+          end
+
+          RSB::Settings.registry.on_change(verification_key) do |_old_value, new_value|
+            if ActiveModel::Type::Boolean.new.cast(new_value)
+              auto = RSB::Settings.get(auto_verify_key)
+              if ActiveModel::Type::Boolean.new.cast(auto)
+                raise RSB::Settings::ValidationError,
+                      "Cannot enable verification_required when auto-verify is enabled for #{defn.label}. Disable auto_verify_on_signup first."
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end