vpndetection 3.1.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec6ec791baf60e18a16396d053982e23588f084125fa8e54d73554cdfabeea26
-  data.tar.gz: 2f8abd7e9159b1ae42840706a8f387602f5a655400634147a7facdeb501a1efe
+  metadata.gz: e3489ebf7b31c0307756abb483614adb213f1b9feb37890ed1e5b1f163f35c02
+  data.tar.gz: b0f1881979f90e0a0378bf399bf1442005c30d1fe775f1c332a71418470799b4
 SHA512:
-  metadata.gz: 9b64120388a69ece3380e2c413f25967738a8afaef826d62d1729ed16fce48b6980bea4b301e8f19d66a2f2f3c4f9e0c1e00d2761e0243b6d8777a9a947f9596
-  data.tar.gz: 8d427526b7b79d44aa777080c140da7e79da69160018cff9766f17b2fe8ccd9464f825173fe8593f5b3e5dae7d3ed94d9d373f0d0df783bbaedf08d9eac2e361
+  metadata.gz: a346d47d4e39b0b0ed62649db5d32bf9718f04e15472ff1a3ca6bf2a470cbc5ef69be8e1bfcaa72078d165724c386e948d1003db7eb0a96a02603b848737c53e
+  data.tar.gz: 72ad76f8e9fed8ac94b3aaee0fea5e82a40746da4c3a0f62c99f6ea4469fc94d13ec23b064de9025b29b44f163d3b5d174a08774bb965fab00c6d190698023df

data/lib/vpndetection/middleware/condition.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module VPNDetection
+  module Middleware
+    # Deciding whether an answer is worth blocking.
+    #
+    # A condition is written in the shape of a served answer and keyed by the
+    # same names the API uses, so what you write here reads like what you get
+    # back. Symbol and string keys both work.
+    #
+    #   { is_vpn: true }
+    #   { is_vpn: true, vpn: { provider: 'nordvpn' } }
+    #   { is_resproxy: true, resproxy: { hits: { gte: 5 } } }
+    #   { vpn: { confidence: %w[high medium] } }
+    #   [{ is_tor: true }, { is_resproxy: true }]   # a list is OR
+    #
+    # A value may be a scalar (equality, strings without regard to case), an
+    # Array meaning any-of, a Hash of `gte`/`gt`/`lte`/`lt` bounding a number,
+    # or a nested condition. A member set to `false` or `nil` is ignored
+    # entirely - a condition states the positive signals you act on, so there is
+    # no way to write "block when this is false", which would otherwise read as
+    # blocking everybody.
+    module Condition
+      BOUND_KEYS = %w[gte gt lte lt].freeze
+
+      module_function
+
+      # Whether an answer satisfies the condition, and should therefore be
+      # blocked.
+      def matches?(condition, result)
+        Array(wrap(condition)).any? { |one| matches_object?(one, result.raw) }
+      end
+
+      # The top-level members a condition names that this answer did not carry.
+      #
+      # A field your plan does not include is absent rather than false, so a
+      # condition naming one can never match and the block would silently never
+      # fire. Gating is per top-level member, which is why only the first path
+      # segment is checked: a detail object present but empty is a real answer
+      # meaning the flag is false, not a plan gap.
+      #
+      # A locally answered bogon needs no special case: it is synthesized in the
+      # widest shape, so every member is present and nothing reads as missing.
+      def missing_members(condition, result)
+        missing = []
+        wrap(condition).each do |one|
+          one.each do |member, want|
+            name = member.to_s
+            next if constraint_count(want).zero? || missing.include?(name)
+
+            missing << name unless result.raw.key?(name)
+          end
+        end
+        missing
+      end
+
+      # Refuse a condition that constrains nothing.
+      #
+      # Ignoring `false` means `{ is_vpn: false }` and `{}` have no terms left
+      # to satisfy, so they would match every answer and block all traffic.
+      # Nobody writes that on purpose, and failing when the middleware is built
+      # beats discovering it in production.
+      def validate!(condition)
+        return if condition.nil?
+
+        wrap(condition).each do |one|
+          next unless constraint_count(one).zero?
+
+          raise ArgumentError,
+                "vpndetection: block condition #{one.inspect} constrains nothing, which " \
+                'would block every request; a member set to false or nil is ignored, so ' \
+                'state the positive signals you act on'
+        end
+      end
+
+      # How many leaf constraints a condition actually carries.
+      def constraint_count(condition)
+        case condition
+        when nil, false then 0
+        when Hash
+          bound?(condition) ? 1 : condition.values.sum { |v| constraint_count(v) }
+        when Array then condition.sum { |v| constraint_count(v) }
+        else 1
+        end
+      end
+
+      def wrap(condition)
+        condition.is_a?(Array) ? condition : [condition]
+      end
+
+      def matches_object?(condition, value)
+        condition.all? do |member, want|
+          next true if constraint_count(want).zero?
+
+          matches_value?(want, value.is_a?(Hash) ? value[member.to_s] : nil)
+        end
+      end
+
+      # An ABSENT member arrives here as nil, which is exactly what "not in your
+      # plan" looks like. Every branch below must therefore reject it, which is
+      # what makes an unserved member fail a match rather than pass it.
+      def matches_value?(want, got)
+        case want
+        when Array then want.any? { |entry| matches_value?(entry, got) }
+        when Hash
+          bound?(want) ? matches_bound?(want, got) : matches_object?(want, got)
+        when String
+          # Providers are lowercase slugs on the wire and a caller should not
+          # have to know that, so a string compares without case.
+          got.is_a?(String) && want.casecmp?(got)
+        when true, false then want == got
+        when Numeric then got.is_a?(Numeric) && !got.is_a?(TrueClass) && want == got
+        else want == got
+        end
+      end
+
+      def matches_bound?(bound, got)
+        return false unless got.is_a?(Numeric)
+
+        normalized = bound.transform_keys(&:to_s)
+        return false if normalized['gte'] && got < normalized['gte']
+        return false if normalized['gt'] && got <= normalized['gt']
+        return false if normalized['lte'] && got > normalized['lte']
+
+        !(normalized['lt'] && got >= normalized['lt'])
+      end
+
+      def bound?(value)
+        return false unless value.is_a?(Hash)
+
+        !value.empty? && value.keys.all? { |k| BOUND_KEYS.include?(k.to_s) }
+      end
+    end
+  end
+end

data/lib/vpndetection/middleware/core.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require_relative 'condition'
+
+module VPNDetection
+  # The framework-agnostic half of a web middleware: resolve a client address,
+  # classify it, and decide whether the condition matched.
+  #
+  # An adapter - the vpndetection-rails gem - keeps only the parts that are
+  # genuinely framework-shaped and shares everything here, so the shared
+  # conformance corpus is asserted once for Ruby rather than once per framework.
+  module Middleware
+    # What a middleware attached to the request, whether or not it succeeded.
+    Lookup = Struct.new(:blocked, :ip, :result, :error, keyword_init: true) do
+      # Whether the condition matched. Always false when none was configured.
+      def blocked?
+        blocked == true
+      end
+    end
+
+    # Enough of an incoming request for a selector to work with, whatever
+    # framework it came from. An adapter supplies one of these per request.
+    RequestView = Struct.new(:header, :framework_ip, keyword_init: true)
+
+    # Defaults set for a request path rather than for a script: failing open
+    # quickly beats holding a visitor while we try again.
+    DEFAULT_TIMEOUT = 2.5
+    DEFAULT_RETRIES = 0
+
+    # Resolve, classify, decide.
+    class Core
+      # @param default_ip_selector [#call] the framework's own accessor, used
+      #   when the caller named none.
+      def initialize(default_ip_selector, **options)
+        Condition.validate!(options[:block_condition])
+        @condition = options[:block_condition]
+        @selector = options[:ip_selector] || default_ip_selector
+        @fail_closed = options.fetch(:fail_closed, false)
+        @on_missing_field = options.fetch(:on_missing_field, :warn)
+        @skip = options[:skip]
+        @on_warn = options[:on_warn]
+        @retries = options.fetch(:retries, DEFAULT_RETRIES)
+        @warned = {}
+        @client = options[:client] || Client.new(
+          api_key: options[:api_key],
+          **{ base_url: options[:base_url] }.compact,
+          timeout: options.fetch(:timeout, DEFAULT_TIMEOUT)
+        )
+      end
+
+      # Whether a condition was configured at all.
+      def blocking?
+        !@condition.nil?
+      end
+
+      # Classify one request. Answers nil when `skip` claimed it.
+      #
+      # A failed LOOKUP is not raised: it lands on `Lookup#error` and the
+      # request is let through. What CAN raise is a misconfiguration - a
+      # condition naming a member the plan does not serve, with
+      # `on_missing_field: :raise`.
+      def evaluate(request)
+        return nil if @skip&.call(request)
+
+        ip = @selector.call(request).to_s.strip
+        return unresolved if ip.empty?
+
+        if Bogon.bogon?(ip)
+          # Expected in local development. Anywhere else it means a proxy sits
+          # in front and its own address is what reached us.
+          warn_once(
+            "resolved the client address as #{ip}, which is not a public address. If this " \
+            'application runs behind a proxy or load balancer, configure its trusted-proxy ' \
+            "setting or pass an ip_selector that reads your edge's header."
+          )
+        end
+
+        begin
+          result = @client.lookup(ip, retries: @retries)
+        rescue VPNDetection::Error => e
+          return Lookup.new(blocked: @fail_closed, ip: ip, error: e)
+        end
+        decide(ip, result)
+      end
+
+      private
+
+      def unresolved
+        warn_once(
+          'could not resolve a client address from this request; pass an ip_selector that ' \
+          'knows where yours comes from'
+        )
+        Lookup.new(
+          blocked: @fail_closed,
+          error: VPNDetection::Error.new(:bad_request, 'no client address on the request')
+        )
+      end
+
+      def decide(ip, result)
+        return Lookup.new(blocked: false, ip: ip, result: result) if @condition.nil?
+
+        report_missing(result)
+        Lookup.new(
+          blocked: Condition.matches?(@condition, result),
+          ip: ip,
+          result: result
+        )
+      end
+
+      def report_missing(result)
+        return if @on_missing_field == :ignore
+
+        missing = Condition.missing_members(@condition, result)
+        return if missing.empty?
+
+        message = "block_condition names #{missing.join(', ')}, which your plan does not " \
+                  'include, so those terms can never match. An absent member means "not in ' \
+                  'your plan", not "checked, and no".'
+        raise ArgumentError, "vpndetection: #{message}" if @on_missing_field == :raise
+
+        warn_once(message)
+      end
+
+      # A misconfiguration is the same on every request, so saying so once is a
+      # warning and saying so a million times is an outage of its own.
+      def warn_once(message)
+        return if @warned[message]
+
+        @warned[message] = true
+        @on_warn ? @on_warn.call(message) : Kernel.warn("[vpndetection] #{message}")
+      end
+    end
+
+    # The shared client-address selectors, bound to one framework's request type.
+    #
+    # There is no portable default: a framework's own accessor may return the
+    # socket peer, or may already have walked a proxy chain, depending on the
+    # framework and on how the application configured it.
+    class Selectors
+      def initialize(&view)
+        @view = view
+      end
+
+      # The framework's own client-address accessor.
+      def default
+        ->(request) { @view.call(request).framework_ip.call }
+      end
+
+      # An address from `X-Forwarded-For`.
+      #
+      # The LEFT-MOST entry (depth 0) is whatever the caller sent, because
+      # proxies append to this header, so a visitor who sets it themselves
+      # appears first and this returns their forgery. It is only trustworthy
+      # when an edge you control overwrites the header. When you know how many
+      # proxies sit in front, count from the right: depth 1 is the address your
+      # nearest proxy saw.
+      def xff(depth = 0)
+        lambda do |request|
+          seen = @view.call(request)
+          chain = (seen.header.call('X-Forwarded-For') || '').split(',').map(&:strip).reject(&:empty?)
+          next seen.framework_ip.call if chain.empty?
+          next chain.first if depth <= 0 || depth > chain.length
+
+          chain[-depth]
+        end
+      end
+
+      # An address from a single-value header your edge writes -
+      # `header('CF-Connecting-IP')` behind Cloudflare. Falls back to the
+      # framework's accessor when the header is absent.
+      def header(name)
+        lambda do |request|
+          seen = @view.call(request)
+          value = (seen.header.call(name) || '').strip
+          value.empty? ? seen.framework_ip.call : value
+        end
+      end
+    end
+  end
+end

data/lib/vpndetection/middleware.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'middleware/condition'
+require_relative 'middleware/core'

data/lib/vpndetection/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module VPNDetection
-  VERSION = '3.1.0'
+  VERSION = '3.2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vpndetection
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.2.0
 platform: ruby
 authors:
 - Mslm Dev
@@ -60,6 +60,9 @@ files:
 - lib/vpndetection/configuration.rb
 - lib/vpndetection/database_api.rb
 - lib/vpndetection/errors.rb
+- lib/vpndetection/middleware.rb
+- lib/vpndetection/middleware/condition.rb
+- lib/vpndetection/middleware/core.rb
 - lib/vpndetection/models/class_detail.rb
 - lib/vpndetection/models/database.rb
 - lib/vpndetection/models/database_checksums_response.rb