add_auth 0.2.2 → 0.4.0

data/lib/add_auth/rails/migration/account_store.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "add_auth/rails/stores/account_lock"
+
+module AddAuth
+  module Rails
+    module Migration
+      class AccountStore
+        FIELDS = {id: :id, email: :email, encrypted_password: :encrypted_password,
+                  authority: :add_auth_authority, migration_stamp: :add_auth_migration_stamp,
+                  email_address: :email_address, password_digest: :password_digest, scheme: :add_auth_password_scheme}.freeze
+
+        def initialize(user_model:)
+          @users = user_model
+          @lock = Stores::AccountLock.new(user_model)
+          unless @users.primary_key == "id" && (FIELDS.values.map(&:to_s) - @users.column_names).empty?
+            raise ArgumentError, "prepare the reviewed User account schema before conversion"
+          end
+        end
+
+        def source_page(after:, limit:)
+          scope = @users.unscoped.order(:id)
+          scope = scope.where(@users.arel_table[:id].gt(after)) if after
+          scope.limit(limit).pluck(*FIELDS.values).map { |row| FIELDS.keys.zip(row).to_h }
+        end
+
+        def with_account(id)
+          @lock.call(id: id) { |user| yield(user && FIELDS.to_h { |name, field| [name, user.read_attribute(field)] }) }
+        rescue ActiveRecord::RecordNotUnique
+          :conflicts
+        end
+
+        def prepare(id:, **attributes)
+          raise AddAuth::Error, "conversion requires an account transaction" unless @users.connection.transaction_open?
+          # Source authority is retained. No callbacks, mail or host provisioning.
+          @users.unscoped.where(id: id).update_all(attributes)
+        end
+      end
+    end
+  end
+end

data/lib/add_auth/rails/migration/effective_inventory.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "add_auth/core/migration/readiness"
+
+module AddAuth
+  module Rails
+    module Migration
+      class EffectiveInventory
+        LIMIT = 10_000
+        ACCOUNT_FIELDS = %w[email email_address encrypted_password password_digest confirmed_at unconfirmed_email locked_at failed_attempts disabled_at deleted_at remember_created_at reset_password_token confirmation_token unlock_token authentication_token provider uid].freeze
+        OPTIONS = %i[authentication_keys case_insensitive_keys strip_whitespace_keys stretches password_length reconfirmable allow_unconfirmed_access_for confirm_within reset_password_within maximum_attempts unlock_strategy unlock_in remember_for sign_in_after_reset_password].freeze
+
+        def initialize(limit: LIMIT)
+          raise ArgumentError, "limit must be between 1 and 100000" unless limit.is_a?(Integer) && limit.between?(1, 100_000)
+          @limit = limit
+        end
+
+        def call
+          unless %w[test development].include?(::Rails.env.to_s) && defined?(::Devise)
+            raise ArgumentError, "effective preflight requires a local test/development Devise host"
+          end
+          @complete = true
+          mappings = ::Devise.mappings.values
+          models = mappings.map(&:to).uniq
+          connections = models.map(&:connection_pool).uniq
+          raise ArgumentError, "inspect one Active Record connection pool at a time" unless connections.length == 1
+          accounts = read_only(connections.first) { models.map { |model| account(model) } }
+          all_modules = accounts.flat_map { |entry| entry[:modules] }.uniq
+          facts = {mode: "effective", complete: @complete, row_limit: @limit,
+                   versions: %w[devise rails bcrypt].to_h { |name| [name.to_sym, Gem.loaded_specs[name]&.version&.to_s] }.merge(ruby: RUBY_VERSION),
+                   scope_count: mappings.length, modules: all_modules & Core::Migration::Readiness::MODULES,
+                   unknown_modules: accounts.sum { |entry| entry[:unknown_modules] },
+                   extensions: Core::Migration::Readiness::EXTENSIONS.select { |name| Gem.loaded_specs.key?(name) },
+                   rails_contract: accounts.length == 1 && accounts.first[:rails_contract], accounts: accounts}
+          Core::Migration::Readiness.new.call(facts)
+        end
+
+        private
+
+        def read_only(pool)
+          pool.with_connection do |connection|
+            raise ArgumentError, "effective preflight requires its own transaction" if connection.transaction_open?
+            case connection.adapter_name
+            when "PostgreSQL"
+              connection.transaction(requires_new: true) do
+                connection.execute("SET TRANSACTION ISOLATION LEVEL REPEATABLE READ, READ ONLY")
+                connection.execute("SET LOCAL statement_timeout = '10s'")
+                yield
+              end
+            when "SQLite"
+              previous = connection.select_value("PRAGMA query_only").to_i
+              begin
+                connection.execute("PRAGMA query_only = ON")
+                # Rails 8.1 starts ordinary SQLite transactions with BEGIN
+                # IMMEDIATE, which requests write authority even for SELECTs.
+                connection.execute("BEGIN DEFERRED TRANSACTION")
+                begin
+                  yield
+                ensure
+                  connection.execute("ROLLBACK")
+                end
+              ensure
+                connection.execute("PRAGMA query_only = #{previous}")
+              end
+            else
+              raise ArgumentError, "effective preflight supports SQLite and PostgreSQL only"
+            end
+          end
+        end
+
+        def account(model)
+          columns = model.columns_hash
+          fields = ACCOUNT_FIELDS & columns.keys
+          # No model instances, callbacks, password verification or normalization hooks.
+          rows = model.unscoped.limit(@limit + 1).pluck(*fields).map { |values| fields.zip(Array(values)).to_h }
+          @complete = false if rows.length > @limit
+          rows = rows.first(@limit)
+          modules = model.devise_modules.map(&:to_s)
+          lookup_keys = Array(model.authentication_keys)
+          identifier = (lookup_keys.length == 1 && fields.include?(lookup_keys.first.to_s)) ? lookup_keys.first.to_s : "email"
+          @complete = false unless lookup_keys == [:email] || lookup_keys == [:email_address]
+          password = fields.include?("encrypted_password") ? "encrypted_password" : "password_digest"
+          keys = rows.map { |row| row[identifier].to_s.strip.downcase }
+          nonblank = keys.reject(&:empty?)
+          options = OPTIONS.filter_map { |name| [name, safe_option(model.public_send(name))] if model.respond_to?(name) }.to_h
+          verifier = model.instance_method(:valid_password?).source_location&.first
+          devise_root = Gem.loaded_specs.fetch("devise").full_gem_path + "/"
+          indexes = model.connection.indexes(model.table_name)
+          {model: safe_name(model.name), table: safe_name(model.table_name),
+           primary_key_type: columns[model.primary_key]&.type&.to_s,
+           database: model.connection.adapter_name, identifier: identifier,
+           identifier_type: columns[identifier]&.type&.to_s,
+           identifier_collation: columns[identifier]&.respond_to?(:collation) ? safe_name(columns[identifier].collation) : nil,
+           unique_identifier_index: indexes.any? { |index| index.unique && index.columns == [identifier] && !index.where },
+           modules: modules & Core::Migration::Readiness::MODULES,
+           unknown_modules: (modules - Core::Migration::Readiness::MODULES).length,
+           options: options, pepper_configured: model.respond_to?(:pepper) && !model.pepper.to_s.empty?,
+           custom_verifier: !verifier&.start_with?(devise_root) || !model.instance_method(:password=).source_location&.first&.start_with?(devise_root),
+           rails_contract: (model.name == "User" && fields.include?("email_address") && fields.include?("password_digest") && model.respond_to?(:authenticate_by) && defined?(::Session) && defined?(::Authentication)) ? true : false,
+           related_tables: related_tables(model),
+           counts: {inspected: rows.length, missing_identifier: keys.count(&:empty?), identifier_collisions: nonblank.length - nonblank.uniq.length,
+                    unknown_password: rows.count { |row| !row[password].to_s.match?(/\A\$2[aby]\$\d{2}\$[.\/A-Za-z0-9]{53}\z/) },
+                    unconfirmed: fields.include?("confirmed_at") ? rows.count { |row| row["confirmed_at"].nil? } : 0,
+                    reconfirming: rows.count { |row| !row["unconfirmed_email"].to_s.empty? },
+                    locked: rows.count { |row| row["locked_at"] }, disabled: rows.count { |row| row["disabled_at"] },
+                    deleted: rows.count { |row| row["deleted_at"] },
+                    outstanding_authority: rows.count { |row| %w[remember_created_at reset_password_token confirmation_token unlock_token authentication_token].any? { |key| !row[key].to_s.empty? } }}}
+        end
+
+        def related_tables(model)
+          connection = model.connection
+          tables = connection.tables.sort
+          @complete = false if tables.length > 200
+          tables.first(200).filter_map do |table|
+            next if table == model.table_name
+            columns = connection.columns(table).to_h { |column| [column.name, column] }
+            foreign_keys = connection.foreign_keys(table).select { |key| key.to_table == model.table_name }
+            reference = foreign_keys.first&.column || ("user_id" if model.name == "User" && columns.key?("user_id"))
+            next unless reference && columns.key?(reference)
+            quoted_table = connection.quote_table_name(table)
+            quote = ->(name) { connection.quote_column_name(name) }
+            identity_fields = %w[provider issuer subject uid] & columns.keys
+            selected = [reference, *identity_fields]
+            records = connection.select_rows("SELECT #{selected.map { |field| quote.call(field) }.join(", ")} FROM #{quoted_table} LIMIT #{@limit + 1}")
+            @complete = false if records.length > @limit
+            records = records.first(@limit)
+            identities = identity_fields.empty? ? [] : records.map { |row| row.drop(1) }
+            account_table = connection.quote_table_name(model.table_name)
+            key = quote.call(model.primary_key)
+            reference_column = quote.call(reference)
+            orphan_count = connection.select_value(<<~SQL).to_i
+              SELECT COUNT(*) FROM
+                (SELECT #{reference_column} FROM #{quoted_table} LIMIT #{@limit + 1}) source
+              LEFT JOIN #{account_table} account ON account.#{key} = source.#{reference_column}
+              WHERE source.#{reference_column} IS NOT NULL AND account.#{key} IS NULL
+            SQL
+            {table: safe_name(table), reference: safe_name(reference), key_type: columns[reference].type.to_s,
+             foreign_key_enforced: foreign_keys.any?, inspected: records.length,
+             orphaned_references: orphan_count, duplicate_identities: identities.length - identities.uniq.length}
+          end
+        end
+
+        def safe_name(value)
+          value.to_s.match?(/\A[A-Za-z_]\w*(?:::\w+)*\z/) ? value.to_s : nil
+        end
+
+        def safe_option(value)
+          case value
+          when nil, true, false, Numeric then value
+          when Symbol then safe_name(value)
+          when Range then [safe_option(value.begin), safe_option(value.end), value.exclude_end?]
+          when Array then value.map { |item| safe_option(item) }
+          when Hash then value.to_h { |key, item| [safe_name(key), safe_option(item)] }
+          else
+            # ActiveSupport::Duration exposes only a numeric duration.
+            value.is_a?(ActiveSupport::Duration) ? value.to_i : "custom"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/add_auth/rails/migration/key_type.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Rails
+    module Migration
+      module KeyType
+        module_function
+
+        # Resolve when the migration runs, after the host's account table exists.
+        # Session IDs remain integer until opaque cursor support is established.
+        def for(connection, table, session: false)
+          key = connection.primary_key(table)
+          column = connection.columns(table).find { |entry| entry.name == key }
+          raise ArgumentError, "AddAuth requires a single integer or UUID primary key on #{table}" unless column
+          return :bigint if column.type == :integer && column.limit == 8
+          return :integer if column.type == :integer
+          return :uuid if column.type == :uuid && !session
+          raise ArgumentError, session ? "AddAuth requires integer Session IDs; UUID accounts can use integer Sessions" : "AddAuth requires an integer or UUID account primary key"
+        end
+      end
+    end
+  end
+end

data/lib/add_auth/rails/migration/source_bridge.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "add_auth/core/migration/account_adoption"
+require "add_auth/rails/stores/account_lock"
+
+module AddAuth
+  module Rails
+    module Migration
+      # Include after Devise in an expanded, reviewed source model. This does
+      # not select routes or retire other host credential readers at cutover.
+      module SourceBridge
+        extend ActiveSupport::Concern
+
+        included do
+          before_save :add_auth_project_source_credentials
+        end
+
+        def valid_password?(password)
+          Core::Migration::AccountAdoption.source_authority?(self[:add_auth_authority]) && super
+        end
+
+        def active_for_authentication?
+          Core::Migration::AccountAdoption.source_authority?(self[:add_auth_authority]) && super
+        end
+
+        # Devise Lockable increments this counter through update_all before its
+        # later save callback. Fence that bypass on the same account row lock.
+        def increment_failed_attempts
+          self.class.transaction do
+            current = Stores::AccountLock.new(self.class).current_in_transaction(id: id)
+            raise AddAuth::Error, "source account no longer exists" unless current
+            Core::Migration::AccountAdoption.authorize_source_write!(authority: current[:add_auth_authority], changed_fields: [:failed_attempts])
+            super
+          end
+        end
+
+        private
+
+        def add_auth_project_source_credentials
+          current = persisted? ? Stores::AccountLock.new(self.class).current_in_transaction(id: id) : self
+          raise AddAuth::Error, "source account no longer exists" unless current
+          source = %i[email encrypted_password].to_h do |name|
+            [name, will_save_change_to_attribute?(name) ? self[name] : current[name]]
+          end
+          attributes = Core::Migration::AccountAdoption.projection_for_write(**source,
+            authority: current[:add_auth_authority], authority_changed: persisted? && will_save_change_to_add_auth_authority?,
+            changed_fields: changed_attribute_names_to_save)
+          attributes.each { |name, value| self[name] = value }
+        end
+      end
+    end
+  end
+end

data/lib/add_auth/rails/password_adoption.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "add_auth/core/passwords/legacy_bcrypt"
+require "add_auth/core/passwords/credential"
+
+module AddAuth
+  module Rails
+    # Include after has_secure_password. Rails owns new assignment and lookup;
+    # Core chooses exactly one verifier for the persisted credential profile.
+    module PasswordAdoption
+      extend ActiveSupport::Concern
+
+      included do
+        self.filter_attributes += [:add_auth_password_scheme]
+        before_save :add_auth_retire_legacy_password
+      end
+
+      def authenticate_password(password)
+        result = Core::Passwords::Credential.new(legacy_verifier: AddAuth.configuration.legacy_password_verifier)
+          .authenticate(user: self, password: password, current: ->(value) { super(value) })
+        result.success? ? result.user : false
+      end
+
+      def authenticate(password) = authenticate_password(password)
+
+      private
+
+      def add_auth_retire_legacy_password
+        # A host's ordinary password assignment replaces the legacy credential.
+        # Direct migration copies do not set the virtual plaintext attribute.
+        self.add_auth_password_scheme = Core::Passwords::Credential.scheme_after_assignment(
+          scheme: add_auth_password_scheme, password: password, digest_changed: will_save_change_to_password_digest?
+        )
+      end
+    end
+  end
+end

data/lib/add_auth/rails/provider_enrollment.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "json"
+require "active_support/message_encryptor"
+
+module AddAuth
+  module Rails
+    # Bounded transport storage for the form collected before provider consent.
+    # This grants no identity/account authority: G3/G4 still consume the exact
+    # verified enrollment transaction inside the new-account transaction.
+    class ProviderEnrollment
+      MAX_BYTES = 4096
+
+      def initialize(model:, digest:, key:)
+        @model, @digest = model, digest
+        @cipher = ActiveSupport::MessageEncryptor.new(key, cipher: "aes-256-gcm", serializer: :json)
+      end
+
+      def write(pending:, identifier:, profile:)
+        return false unless enrollment?(pending) && bounded_profile?(profile) && identifier.is_a?(String)
+        payload = {"identifier" => identifier, "profile" => profile}
+        return false unless JSON.generate(payload).bytesize <= MAX_BYTES
+        ciphertext = @cipher.encrypt_and_sign(payload, purpose: purpose(pending), expires_at: pending.expires_at)
+        row(pending).where(enrollment_payload: nil).update_all(enrollment_payload: ciphertext) == 1
+      rescue JSON::GeneratorError, EncodingError
+        false
+      end
+
+      def read(pending:)
+        return unless enrollment?(pending)
+        ciphertext = row(pending).pick(:enrollment_payload)
+        return unless ciphertext.is_a?(String) && ciphertext.bytesize <= MAX_BYTES * 3
+        payload = @cipher.decrypt_and_verify(ciphertext, purpose: purpose(pending))
+        return unless payload.is_a?(Hash) && payload["identifier"].is_a?(String) && bounded_profile?(payload["profile"])
+        {identifier: payload.fetch("identifier"), profile: payload.fetch("profile").symbolize_keys}
+      rescue ActiveSupport::MessageEncryptor::InvalidMessage
+        nil
+      end
+
+      def erase(pending:)
+        row(pending).update_all(enrollment_payload: nil) if enrollment?(pending)
+      end
+
+      private
+
+      def enrollment?(pending)
+        pending.is_a?(Core::ExternalIdentities::Pending) && pending.purpose == Core::ExternalIdentities::ENROLL
+      end
+
+      def bounded_profile?(profile)
+        profile.is_a?(Hash) && profile.size <= 20 && profile.all? do |name, value|
+          (name.is_a?(String) || name.is_a?(Symbol)) && name.to_s.valid_encoding? && name.to_s.bytesize.between?(1, 64) &&
+            (value.nil? || value == true || value == false || (value.is_a?(String) && value.valid_encoding? && value.bytesize <= 2048))
+        end
+      end
+
+      def purpose(pending) = "add_auth.external-enrollment:#{@digest.digest(pending.id)}"
+      def row(pending) = @model.where(digest: @digest.digest(pending.id))
+    end
+  end
+end

data/lib/add_auth/rails/provider_libraries/apple_form_post_correlation.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "active_support/message_encryptor"
+require "rack/request"
+require "rack/utils"
+
+module AddAuth
+  module Rails
+    module ProviderLibraries
+      # OmniAuth's Apple strategy binds state and nonce to rack.session. Apple
+      # posts its callback cross-site, where a normal SameSite=Lax Rails session
+      # is intentionally absent. This tiny Rack wrapper copies only those
+      # verifier inputs and the Core browser correlation into a separately
+      # encrypted, HttpOnly, Secure, SameSite=None cookie scoped to Apple's
+      # callback path. It never changes the application's normal session cookie.
+      class AppleFormPostCorrelation
+        COOKIE = "add_auth_apple_callback"
+        PENDING_KEY = "add_auth.apple_pending"
+        START_PATH = "/auth/apple"
+        CALLBACK_PATH = "/auth/apple/callback"
+        PURPOSE = "add_auth.apple-form-post.v1"
+
+        def self.remember!(session:, transaction:, browser_secret:, configuration_id:, purpose:, remember: false)
+          raise ArgumentError, "Apple provider transaction is invalid" unless text?(transaction)
+          raise ArgumentError, "Apple provider browser secret is invalid" unless text?(browser_secret)
+          raise ArgumentError, "Apple provider configuration is invalid" unless text?(configuration_id)
+          raise ArgumentError, "Apple provider purpose is invalid" unless text?(purpose.to_s)
+
+          session[PENDING_KEY] = {"transaction" => transaction, "browser_secret" => browser_secret,
+                                  "configuration_id" => configuration_id, "purpose" => purpose.to_s, "remember" => remember == true}
+        end
+
+        def self.text?(value)
+          value.is_a?(String) && value.valid_encoding? && value.bytesize.between?(1, 2048) && !value.match?(/[\x00-\x1f\x7f]/)
+        end
+        private_class_method :text?
+
+        def initialize(app, key:, lifetime: 600, clock: -> { Time.now })
+          raise ArgumentError, "Apple callback key must be 32 bytes" unless key.is_a?(String) && key.bytesize == 32
+          raise ArgumentError, "Apple callback lifetime must be positive" unless lifetime.is_a?(Integer) && lifetime.positive?
+
+          @app = app
+          @cipher = ActiveSupport::MessageEncryptor.new(key, cipher: "aes-256-gcm", serializer: :json)
+          @lifetime, @clock = lifetime, clock
+        end
+
+        def call(env)
+          request = Rack::Request.new(env)
+          return request.post? ? start(env) : @app.call(env) if request.path_info == START_PATH
+          return callback(env, request) if request.path_info == CALLBACK_PATH
+
+          @app.call(env)
+        end
+
+        private
+
+        def start(env)
+          pending = env.fetch("rack.session", {}).delete(PENDING_KEY)
+          return @app.call(env) if pending.nil?
+          return failure unless pending.is_a?(Hash) && valid_pending?(pending)
+
+          status, headers, body = @app.call(env)
+          return [status, headers, body] unless status.between?(300, 399)
+
+          payload = pending.merge("state" => env.fetch("rack.session", {})["omniauth.state"],
+            "nonce" => env.fetch("rack.session", {})["omniauth.nonce"])
+          return [status, headers, body] unless valid_payload?(payload)
+
+          write_cookie(headers, encrypt(payload))
+          [status, headers, body]
+        end
+
+        def callback(env, request)
+          # Do not claim a host-owned Apple callback without our capsule. A
+          # request reaching AddAuth's controller still needs valid correlation.
+          return @app.call(env) unless request.cookies.key?(COOKIE)
+          payload = decrypt(request.cookies[COOKIE])
+          return failure unless valid_payload?(payload)
+
+          session = env.fetch("rack.session", {})
+          session["omniauth.state"] = payload.fetch("state")
+          session["omniauth.nonce"] = payload.fetch("nonce")
+          env["add_auth.apple_correlation"] = payload.slice("transaction", "browser_secret", "configuration_id", "purpose", "remember")
+          status, headers, body = @app.call(env)
+          clear_cookie(headers)
+          [status, headers, body]
+        end
+
+        def valid_pending?(payload)
+          self.class.send(:text?, payload["transaction"]) && self.class.send(:text?, payload["browser_secret"]) &&
+            self.class.send(:text?, payload["configuration_id"]) && self.class.send(:text?, payload["purpose"]) &&
+            [true, false].include?(payload["remember"])
+        end
+
+        def valid_payload?(payload)
+          payload.is_a?(Hash) && valid_pending?(payload) && self.class.send(:text?, payload["state"]) && self.class.send(:text?, payload["nonce"])
+        end
+
+        def encrypt(payload)
+          @cipher.encrypt_and_sign(payload, purpose: PURPOSE, expires_in: @lifetime)
+        end
+
+        def decrypt(value)
+          return unless self.class.send(:text?, value)
+
+          @cipher.decrypt_and_verify(value, purpose: PURPOSE)
+        rescue ActiveSupport::MessageEncryptor::InvalidMessage
+          nil
+        end
+
+        def write_cookie(headers, value)
+          Rack::Utils.set_cookie_header!(headers, COOKIE, value: value, path: CALLBACK_PATH, secure: true,
+            httponly: true, same_site: :none, max_age: @lifetime)
+        end
+
+        def clear_cookie(headers)
+          Rack::Utils.set_cookie_header!(headers, COOKIE, value: "", path: CALLBACK_PATH, secure: true,
+            httponly: true, same_site: :none, max_age: 0)
+        end
+
+        def failure
+          [422, {"content-type" => "text/plain", "cache-control" => "no-store"}, ["Provider sign-in could not be verified."]]
+        end
+      end
+    end
+  end
+end

data/lib/add_auth/rails/provider_libraries/apple_jwks.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+
+module AddAuth
+  module Rails
+    module ProviderLibraries
+      class AppleJwks
+        URL = URI("https://appleid.apple.com/auth/keys").freeze
+        CACHE_KEY = "add_auth:apple:jwks:v1"
+        MAX_BYTES = 65_536
+
+        def initialize(cache:)
+          @cache = cache
+        end
+
+        # ruby-jwt's key finder requests one invalidation on an unknown kid.
+        # No request/header claim selects a URL or changes TLS verification.
+        def call(options = {})
+          cached = cache_operation { @cache.read(CACHE_KEY) } unless options[:invalidate]
+          return cached if valid?(cached)
+          keys = fetch
+          cache_operation { @cache.write(CACHE_KEY, keys, expires_in: 3600) }
+          keys
+        end
+
+        private
+
+        def cache_operation
+          yield
+        rescue
+          raise AddAuth::Error, "Apple signing keys unavailable", cause: nil
+        end
+
+        def fetch
+          body = +""
+          Timeout.timeout(5) do
+            Net::HTTP.start(URL.host, URL.port, use_ssl: true, open_timeout: 2, read_timeout: 3, write_timeout: 3) do |http|
+              http.max_retries = 0
+              http.request(Net::HTTP::Get.new(URL.request_uri)) do |response|
+                raise AddAuth::Error, "Apple signing keys unavailable" unless response.code == "200"
+                response.read_body do |part|
+                  raise AddAuth::Error, "Apple signing keys unavailable" if body.bytesize + part.bytesize > MAX_BYTES
+                  body << part
+                end
+              end
+            end
+          end
+          keys = JSON.parse(body)
+          raise AddAuth::Error, "Apple signing keys unavailable" unless valid?(keys)
+          keys
+        rescue JSON::ParserError, Timeout::Error, SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError
+          raise AddAuth::Error, "Apple signing keys unavailable", cause: nil
+        end
+
+        def valid?(value)
+          value.is_a?(Hash) && value["keys"].is_a?(Array) && value["keys"].size.between?(1, 16) &&
+            value["keys"].all? { |key|
+              key.is_a?(Hash) && key["kty"] == "RSA" && key["alg"] == "RS256" &&
+                key["kid"].is_a?(String) && key["kid"].bytesize.between?(1, 128) && key["n"].is_a?(String) && key["n"].bytesize.between?(1, 1024) &&
+                key["e"].is_a?(String) && key["e"].bytesize.between?(1, 16)
+            } && value["keys"].map { |key| key["kid"] }.uniq.length == value["keys"].length
+        end
+      end
+    end
+  end
+end

data/lib/add_auth/rails/provider_libraries/apple_native.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# Optional adapter: the host installs and requires ruby-jwt. No OAuth strategy,
+# global library setting or provider credential storage is introduced.
+module AddAuth
+  module Rails
+    module ProviderLibraries
+      module AppleNative
+        ISSUER = "https://appleid.apple.com"
+        PURPOSES = [Core::ExternalIdentities::NATIVE, Core::ExternalIdentities::NATIVE_ENROLL].freeze
+
+        class CallbackResult
+          def self.capture(identity_token:, pending:, nonce:, jwks:)
+            return unless defined?(::JWT) && pending.is_a?(Core::ExternalIdentities::Pending) &&
+              PURPOSES.include?(pending.purpose) && pending.configuration.issuer == ISSUER &&
+              identity_token.is_a?(String) && identity_token.bytesize.between?(1, 16_384) && nonce.is_a?(String)
+            claims, = ::JWT.decode(identity_token, nil, true, algorithms: ["RS256"], jwks: jwks, allow_nil_kid: false,
+              iss: ISSUER, verify_iss: true, aud: pending.configuration.audience, verify_aud: true, verify_iat: true,
+              required_claims: %w[iss aud sub exp iat nonce])
+            signed_nonce = claims["nonce"]
+            return unless signed_nonce.is_a?(String) && signed_nonce.bytesize == nonce.bytesize &&
+              OpenSSL.fixed_length_secure_compare(signed_nonce, nonce) && claims["iat"].is_a?(Integer) && claims["exp"].is_a?(Integer) &&
+              claims["iat"] >= pending.issued_at.to_i && claims["aud"] == pending.configuration.audience
+            new(pending: pending, subject: claims["sub"])
+          rescue ::JWT::DecodeError, ArgumentError
+            nil
+          end
+
+          def initialize(pending:, subject:)
+            @transaction_id = pending.id
+            @configuration = pending.configuration
+            @purpose = pending.purpose
+            @subject = Core::ExternalIdentities::Configuration.text(subject)
+            freeze
+          end
+          private_class_method :new
+
+          def verified_claims(transaction:)
+            return unless transaction.is_a?(Core::ExternalIdentities::Pending) && transaction.id == @transaction_id &&
+              transaction.configuration.equal?(@configuration) && transaction.purpose == @purpose
+            {issuer: ISSUER, audience: @configuration.audience, subject: @subject, provenance: "ruby-jwt/apple-native-v1"}
+          end
+
+          def inspect = "#<AddAuth::Rails::ProviderLibraries::AppleNative::CallbackResult [FILTERED]>"
+        end
+
+        class Verifier
+          def call(server_result:, transaction:)
+            server_result.verified_claims(transaction: transaction) if server_result.is_a?(CallbackResult)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/add_auth/rails/provider_libraries/callback_route.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Rails
+    module ProviderLibraries
+      # Routing selects only host-registered AddAuth providers. Authentication
+      # and transaction ownership are checked later by the library and Core.
+      class CallbackRoute
+        def self.matches?(request)
+          options = AddAuth.configuration.external_identities
+          options.enabled && options.providers.any? { |provider| provider.middleware_name == request.path_parameters[:provider] }
+        end
+      end
+    end
+  end
+end