add_auth 0.2.2 → 0.4.0

data/lib/add_auth/core/mobile_handoffs.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "digest"
+require "base64"
+
+module AddAuth
+  module Core
+    # The native verifier protects this application handoff. It does not replace
+    # upstream provider state/nonce/PKCE, which remain the library's responsibility.
+    class MobileHandoffs
+      PURPOSE = ExternalIdentities::MOBILE
+      CODE = /\Aah1:[A-Za-z0-9_-]{43}\z/
+      STATE = /\A[A-Za-z0-9_-]{43,128}\z/
+      VERIFIER = /\A[A-Za-z0-9._~-]{43,128}\z/
+      CHALLENGE = /\A[A-Za-z0-9_-]{43}\z/
+      Handoff = Struct.new(:code, :state, :callback) do
+        def inspect = "#<AddAuth::Core::MobileHandoffs::Handoff [FILTERED]>"
+      end
+
+      def initialize(store:, profile:, sessions:, access_policy:, digest:, clock: Time, lifetime: 60)
+        raise ArgumentError, "handoff lifetime must be between 1 and 120 seconds" unless lifetime.is_a?(Integer) && lifetime.between?(1, 120)
+        @store, @profile, @sessions, @access, @digest, @clock, @lifetime = store, profile, sessions, access_policy, digest, clock, lifetime
+      end
+
+      def begin_transaction(pending:, client_id:, callback:, state:, code_challenge:, code_challenge_method:)
+        return failure unless pending.is_a?(ExternalIdentities::Pending) && pending.purpose == PURPOSE &&
+          @profile&.client?(client_id) && @profile.callback(client_id) == callback && callback &&
+          text?(state, STATE) && text?(code_challenge, CHALLENGE) && code_challenge_method == "S256" &&
+          pending.issued_at <= @clock.now && pending.expires_at > @clock.now
+        row = @store.create_pending(external_digest: @digest.digest(pending.id), client_id: client_id, callback: callback,
+          state: state, challenge_digest: @digest.digest(code_challenge), issued_at: pending.issued_at, expires_at: pending.expires_at)
+        row ? Result.success(user: nil, strategy: :external_identity) : failure
+      end
+
+      # Called only from ExternalIdentities' verified binding finalizer, inside
+      # the owning account transaction. No Session or bearer exists at this point.
+      def issue_in_transaction(user:, proof:, pending:)
+        return failure unless proof.is_a?(ExternalIdentities::SessionProof) && proof.user_id == user.id && pending.purpose == PURPOSE
+        row = @store.by_external_digest(digest: @digest.digest(pending.id))
+        return failure unless row && current_profile?(row) && !row.digest && !row.consumed_at && row.expires_at > @clock.now
+        code = "ah1:#{SecureRandom.urlsafe_base64(32)}"
+        issued = @store.issue(row: row, user_id: user.id, digest: @digest.digest(code),
+          credential_id: proof.credential_id, credential_version: proof.credential_version,
+          policy_version: @access.version(user), authenticated_at: proof.verified_at,
+          expires_at: [row.expires_at, @clock.now + @lifetime].min)
+        return failure unless issued
+        Result.success(user: user, strategy: :external_identity, credential: Handoff.new(code: code, state: row.state, callback: row.callback))
+      end
+
+      def exchange(code:, state:, code_verifier:, client_id:, ip: nil, user_agent: nil)
+        return failure unless @profile&.client?(client_id) && text?(code, CODE) && text?(state, STATE) && text?(code_verifier, VERIFIER)
+        challenge = Base64.urlsafe_encode64(::Digest::SHA256.digest(code_verifier), padding: false)
+        @store.with_code(digest: @digest.digest(code)) do |user, row|
+          now = @clock.now
+          next failure unless user && row && current_profile?(row) && row.client_id == client_id &&
+            @digest.matches?(row.challenge_digest, challenge) && @digest.matches?(@digest.digest(row.state), state)
+          next failure(:consumed_token) if row.consumed_at
+          next failure(:expired_token) unless row.issued_at <= now && row.expires_at > now
+          next failure unless row.policy_version == @access.version(user)
+          proof = ExternalIdentities::SessionProof.send(:new, user_id: user.id, credential_id: row.credential_id,
+            credential_version: row.credential_version, verified_at: row.authenticated_at)
+          grant = @sessions.create_in_transaction(user: user, method: :external_identity, proof: proof,
+            transport: :mobile, client_id: row.client_id, ip_address: hint(ip, 128), user_agent: hint(user_agent, 512))
+          next failure unless grant
+          # Session creation and consume commit together. An unexpected lost CAS
+          # rolls back issuance; it must never return a credential for this request.
+          raise AddAuth::Error, "mobile handoff could not finalize" unless @store.consume(row: row, at: now)
+          Result.success(user: user, strategy: :external_identity, session: grant.session, grant: grant)
+        end
+      end
+
+      private
+
+      def current_profile?(row) = @profile&.client?(row.client_id) && @profile.callback(row.client_id) == row.callback
+      def text?(value, pattern) = value.is_a?(String) && value.ascii_only? && pattern.match?(value)
+      def failure(reason = :invalid_credentials) = Result.failure(reason: reason)
+
+      def hint(value, limit)
+        value if value.is_a?(String) && value.valid_encoding? && value.bytesize <= limit && !value.match?(/[\x00-\x1f\x7f]/)
+      end
+    end
+  end
+end

data/lib/add_auth/core/mobile_profile.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module AddAuth
+  module Core
+    # Host-selected finite API sessions. Client identifiers select configuration,
+    # never prove application identity or authorize an account.
+    class MobileProfile
+      PATTERN = /\Aam1:[A-Za-z0-9_-]{43}\z/
+      attr_reader :lifetime, :idle_timeout, :clients
+
+      def initialize(lifetime:, idle_timeout:, clients:, callbacks: {})
+        unless [lifetime, idle_timeout].all? { |value| value.is_a?(Integer) && value.between?(60, 90 * 86_400) } && idle_timeout <= lifetime
+          raise ArgumentError, "mobile timeouts must be explicit, finite and at most 90 days"
+        end
+        unless clients.is_a?(Array) && clients.size.between?(1, 32) && clients.uniq == clients &&
+            clients.all? { |value| value.is_a?(String) && value.match?(/\A[a-z][a-z0-9_-]{0,63}\z/) }
+          raise ArgumentError, "register bounded mobile client identifiers"
+        end
+        @lifetime, @idle_timeout = lifetime, idle_timeout
+        @clients = clients.map { |client| client.dup.freeze }.freeze
+        unless callbacks.is_a?(Hash) && callbacks.all? { |client, callback| client?(client) && valid_callback?(callback) }
+          raise ArgumentError, "register exact mobile callbacks without query, fragment or credentials"
+        end
+        @callbacks = callbacks.to_h { |client, callback| [client.dup.freeze, callback.dup.freeze] }.freeze
+        freeze
+      end
+
+      def client?(id) = id.is_a?(String) && clients.include?(id)
+      def callback(client_id) = @callbacks[client_id]
+      def bearer = "am1:#{SecureRandom.urlsafe_base64(32)}"
+
+      private
+
+      def valid_callback?(value)
+        return false unless value.is_a?(String) && value.ascii_only? && value.bytesize.between?(10, 2048) && !value.match?(/[\x00-\x20\x7f\\%]/)
+        uri = URI.parse(value)
+        uri.scheme && !%w[http javascript data file].include?(uri.scheme.downcase) &&
+          uri.host && !uri.host.empty? && uri.path && !uri.path.empty? && !uri.userinfo && !uri.query && !uri.fragment
+      rescue URI::InvalidURIError
+        false
+      end
+    end
+  end
+end

data/lib/add_auth/core/mobile_response.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Core
+    module MobileResponse
+      def self.status(reason)
+        {rate_limited: 429, challenge_unavailable: 503, challenge_rejected: 422, unconfirmed: 403, locked: 423, disabled: 403,
+         elevation_required: 403}.fetch(reason, 401)
+      end
+    end
+  end
+end

data/lib/add_auth/core/native_authentication.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module AddAuth
+  module Core
+    class NativeAuthentication
+      Challenge = Struct.new(:id, :nonce, :expires_at) do
+        def inspect = "#<AddAuth::Core::NativeAuthentication::Challenge [FILTERED]>"
+      end
+
+      def initialize(external_identities:, profile:, providers:, intake:, verify:, accounts: nil)
+        @external, @profile, @providers, @intake, @verify = external_identities, profile, providers, intake, verify
+        unless providers.is_a?(Hash) && providers.all? { |client_id, provider| profile&.client?(client_id) && provider.is_a?(ExternalIdentities::Configuration) }
+          raise ArgumentError, "register a native provider configuration for each supported client"
+        end
+        @providers = providers.dup.freeze
+        @accounts = accounts
+      end
+
+      def start(client_id:, ip:, challenge_token: nil, intent: "sign_in")
+        admitted = @intake.anonymous(ip: ip, action: (intent == "enroll") ? :register : :provider, challenge_token: challenge_token)
+        return failure(admitted) if admitted.is_a?(Symbol)
+        provider = @providers[client_id]
+        return failure unless @profile&.client?(client_id) && provider
+        purpose = {"sign_in" => ExternalIdentities::NATIVE, "enroll" => ExternalIdentities::NATIVE_ENROLL}[intent]
+        return failure unless purpose
+        return failure if intent == "enroll" && !@accounts
+        nonce = SecureRandom.urlsafe_base64(32)
+        result = @external.begin_transaction(configuration_id: provider.id, browser_secret: nonce, purpose: purpose,
+          binding_context: context(client_id))
+        return result unless result.success?
+        Result.success(user: nil, strategy: :external_identity,
+          credential: Challenge.new(id: result.credential.id, nonce: nonce, expires_at: result.credential.expires_at))
+      end
+
+      def complete(client_id:, challenge_id:, nonce:, identity_token:, ip:, user_agent: nil)
+        checked = verified(client_id: client_id, challenge_id: challenge_id, nonce: nonce, identity_token: identity_token,
+          ip: ip, purpose: ExternalIdentities::NATIVE)
+        return checked unless checked.success?
+        @external.native_sign_in(evidence: checked.credential, client_id: client_id, ip_address: hint(ip, 128), user_agent: hint(user_agent, 512))
+      end
+
+      def enroll(client_id:, challenge_id:, nonce:, identity_token:, ip:, identifier:, profile: {})
+        return failure(:disabled) unless @accounts
+        checked = verified(client_id: client_id, challenge_id: challenge_id, nonce: nonce, identity_token: identity_token,
+          ip: ip, purpose: ExternalIdentities::NATIVE_ENROLL)
+        return checked unless checked.success?
+        @accounts.call.register_external(identifier: identifier, evidence: checked.credential, profile: profile)
+      end
+
+      private
+
+      def verified(client_id:, challenge_id:, nonce:, identity_token:, ip:, purpose:)
+        admitted = @intake.anonymous(ip: ip, action: :native_exchange)
+        return failure(admitted) if admitted.is_a?(Symbol)
+        provider = @providers[client_id]
+        return failure unless @profile&.client?(client_id) && provider && identity_token.is_a?(String) &&
+          identity_token.ascii_only? && identity_token.bytesize.between?(1, 16_384)
+        pending = @external.pending(transaction: challenge_id, browser_secret: nonce, binding_context: context(client_id))
+        return failure unless pending && pending.purpose == purpose && pending.configuration.equal?(provider)
+        result = @verify.call(identity_token: identity_token, pending: pending, nonce: nonce)
+        evidence = provider.verify(server_result: result, transaction: pending)
+        return failure unless evidence
+        Result.success(user: nil, strategy: :external_identity, credential: evidence)
+      end
+
+      def context(client_id) = "native:#{client_id}"
+
+      def failure(reason = :invalid_credentials) = Result.failure(reason: reason)
+
+      def hint(value, limit)
+        value if value.is_a?(String) && value.valid_encoding? && value.bytesize <= limit && !value.match?(/[\x00-\x1f\x7f]/)
+      end
+    end
+  end
+end

data/lib/add_auth/core/passwords/bcrypt_support.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "bcrypt"
+
+module AddAuth
+  module Core
+    module Passwords
+      # Explicit metadata support for the stock Rails bcrypt verifier, not an
+      # algorithm detector or authentication proof. Override verifiers supply
+      # their own available?(digest:) contract instead of using this adapter.
+      class BcryptSupport
+        PATTERN = /\A\$2[aby]\$(\d{2})\$[.\/A-Za-z0-9]{53}\z/
+
+        def initialize(maximum_cost: BCrypt::Engine::MAX_COST)
+          @maximum_cost = maximum_cost
+        end
+
+        def available?(digest:)
+          return false unless digest.is_a?(String) && digest.valid_encoding? && digest.bytesize == 60
+          match = PATTERN.match(digest)
+          !!(match && match[1].to_i.between?(BCrypt::Engine::MIN_COST, @maximum_cost))
+        rescue ArgumentError, EncodingError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/add_auth/core/passwords/credential.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "bcrypt"
+
+module AddAuth
+  module Core
+    module Passwords
+      class Credential
+        def self.scheme_after_assignment(scheme:, password:, digest_changed:)
+          (digest_changed && password.is_a?(String) && !password.empty?) ? "rails" : scheme
+        end
+
+        def initialize(legacy_verifier:)
+          @legacy = legacy_verifier
+        end
+
+        def authenticate(user:, password:, current:)
+          return Result.failure(reason: :invalid_credentials) unless password.is_a?(String) && password.valid_encoding? && password.bytesize.between?(1, 1024)
+          verified = case scheme(user)
+          when nil, "rails" then current.call(password)
+          when "devise_bcrypt" then @legacy&.verify(digest: user.password_digest, password: password) == true
+          else false
+          end
+          verified ? Result.success(user: user, strategy: :password) : Result.failure(reason: :invalid_credentials)
+        rescue BCrypt::Errors::InvalidHash, BCrypt::Errors::InvalidSecret, ArgumentError, EncodingError
+          Result.failure(reason: :invalid_credentials)
+        end
+
+        # Availability is not authentication. It asks the explicitly selected
+        # verifier whether it supports this persisted credential with its current
+        # configuration. Older/custom adapters without that contract fail closed.
+        def available?(user:, current:)
+          return false unless user.respond_to?(:password_digest)
+          digest = user.password_digest
+          return false unless digest.is_a?(String) && digest.valid_encoding? && !digest.empty?
+          verifier = case scheme(user)
+          when nil, "rails" then current
+          when "devise_bcrypt" then @legacy
+          end
+          verifier.respond_to?(:available?) && verifier.available?(digest: digest) == true
+        end
+
+        private
+
+        def scheme(user) = user.respond_to?(:add_auth_password_scheme) ? user.add_auth_password_scheme : nil
+      end
+    end
+  end
+end

data/lib/add_auth/core/passwords/legacy_bcrypt.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "bcrypt"
+require "add_auth/core/passwords/bcrypt_support"
+
+module AddAuth
+  module Core
+    module Passwords
+      # Verification only. New password assignment remains the Rails host's job.
+      # The source profile chooses this adapter explicitly; no digest guessing.
+      class LegacyBcrypt
+        PATTERN = BcryptSupport::PATTERN
+
+        def initialize(pepper: -> {}, maximum_cost: 14)
+          raise ArgumentError, "pepper must be callable" unless pepper.respond_to?(:call)
+          raise ArgumentError, "maximum_cost must be between 4 and 20" unless maximum_cost.is_a?(Integer) && maximum_cost.between?(4, 20)
+          @pepper, @maximum_cost = pepper, maximum_cost
+          @support = BcryptSupport.new(maximum_cost: maximum_cost)
+        end
+
+        def available?(digest:)
+          @support.available?(digest: digest) && valid_pepper?(@pepper.call)
+        end
+
+        def verify(digest:, password:)
+          return false unless password.is_a?(String) && password.valid_encoding? && password.bytesize.between?(1, 1024)
+          return false unless @support.available?(digest: digest)
+          pepper = @pepper.call
+          return false unless valid_pepper?(pepper)
+          BCrypt::Password.new(digest).is_password?((pepper.nil? || pepper.empty?) ? password : "#{password}#{pepper}")
+        rescue BCrypt::Errors::InvalidHash, BCrypt::Errors::InvalidSecret, ArgumentError, EncodingError
+          false
+        end
+
+        def inspect = "#<AddAuth::Core::Passwords::LegacyBcrypt [FILTERED]>"
+
+        private
+
+        def valid_pepper?(pepper) = pepper.nil? || (pepper.is_a?(String) && pepper.valid_encoding? && pepper.bytesize <= 1024)
+      end
+    end
+  end
+end

data/lib/add_auth/core/passwords/lifecycle.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Core
+    module Passwords
+      # Called only inside the owning account transaction. The adapter supplies
+      # Rails hashing and persistence; these decisions are shared by entry paths.
+      class Lifecycle
+        def initialize(store:, policy:, enabled:, maximum_attempts: 20, unlock_in: 3600, clock: Time, issue_unlock: ->(_user) {})
+          unless maximum_attempts.is_a?(Integer) && maximum_attempts.between?(1, 100) &&
+              unlock_in.is_a?(Numeric) && unlock_in.finite? && unlock_in.between?(60, 86_400)
+            raise ArgumentError, "configure bounded password attempts and unlock duration"
+          end
+          @store, @policy, @enabled, @maximum, @unlock_in, @clock, @issue_unlock = store, policy, enabled, maximum_attempts, unlock_in, clock, issue_unlock
+        end
+
+        def prepare(user:)
+          return unless @enabled && user && !user.add_auth_manual_lock && user.locked_at &&
+            user.add_auth_locked_until && user.add_auth_locked_until <= @clock.now
+          @store.update_account(user: user, locked_at: nil, add_auth_locked_until: nil, failed_attempts: 0)
+        end
+
+        def verified(user:, password:, valid:, rehash: true)
+          return false unless user && @policy.call(user) == true
+          if valid
+            @store.update_account(user: user, failed_attempts: 0) if @enabled && user.failed_attempts != 0
+            if rehash && user.respond_to?(:add_auth_password_scheme) && user.add_auth_password_scheme == "devise_bcrypt" && assignable?(password)
+              @store.rehash_password(user: user, password: password)
+              @store.revoke_authority(user: user, at: @clock.now)
+            end
+            true
+          else
+            record_failure(user) if @enabled
+            false
+          end
+        end
+
+        private
+
+        def assignable?(password)
+          password.is_a?(String) && password.valid_encoding? && password.bytesize.between?(1, 72) && !password.include?("\0")
+        end
+
+        def record_failure(user)
+          attempts = [user.failed_attempts.to_i + 1, @maximum].min
+          changes = {failed_attempts: attempts}
+          if attempts >= @maximum
+            changes[:locked_at] = @clock.now
+            changes[:add_auth_locked_until] = @clock.now + @unlock_in
+          end
+          @store.update_account(user: user, **changes)
+          if attempts >= @maximum
+            @store.revoke_authority(user: user, at: @clock.now)
+            @issue_unlock.call(user)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/add_auth/core/remaining_factors.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Core
+    # Evaluate against a reloaded account under the credential mutation lock.
+    # Counts must include only this account's live credentials. Feature flags
+    # and method labels alone do not establish a usable remaining factor.
+    class RemainingFactors
+      def initialize(access_policy:, passkey_count:, password_available:)
+        @access, @passkey_count, @password_available = access_policy, passkey_count, password_available
+      end
+
+      def call(user)
+        return true if @access.sign_in_allowed?(user, :passkey) && positive_count?(@passkey_count.call(user))
+        return true if @access.recoverable?(user)
+        @access.sign_in_allowed?(user, :password) && @password_available.call(user) == true
+      end
+
+      private
+
+      def positive_count?(value) = value.is_a?(Integer) && value.positive?
+    end
+  end
+end