vpndetection-rails 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c2ba0f47c359b22c40293f01b23af6f203f70434e34c434183ab2ad9e8055789
+  data.tar.gz: 5b9e2a4ac172e35d4f7bb3aef75effa00d1891a2e96efec6203f9621cd616a7f
+SHA512:
+  metadata.gz: 43a08675b9954f594a9b91f01d29ccaf256f3f7cdee8f3d0d92b7e353c8c6f3905ab3f5da38f3f59b7104f4127aa2887425ef31541b7b4245522d04950323950
+  data.tar.gz: 2dde83ca6fce1c93e006692a8ee5de7cd961f51775b6261351fb6d96db13cb5c0c6084aee0963ff482ee3bd3233a81c60c5b15087ae9c0148b3667d659112a43

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mslm Dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,125 @@
+# [<img src="https://s3.vpndetection.io/vpndetection-public/brand/mark.svg" alt="VPNDetection" width="24"/>](https://vpndetection.io/) VPNDetection Rails Middleware
+
+[![Gem](https://img.shields.io/gem/v/vpndetection-rails.svg)](https://rubygems.org/gems/vpndetection-rails)
+[![license](https://img.shields.io/github/license/vpndetection-io/sdk-ruby-rails.svg)](LICENSE)
+
+The official Rails middleware for the [VPNDetection](https://vpndetection.io) API.
+
+It classifies the visitor behind each request — VPN, residential proxy, Tor, hosting, CDN, relay — and hands the answer to your controllers. Blocking is opt-in.
+
+It is Rack middleware, so it works in Sinatra, Hanami, Roda or a bare Rack app too; the Railtie is only what saves a Rails user from inserting it by hand.
+
+## Getting Started
+
+```bash
+bundle add vpndetection-rails
+```
+
+Requires Ruby 3.1 or newer.
+
+You need an API key. Create one in the [console](https://app.vpndetection.io); the free tier's allowance is counted per source address, and a server is a single source address, so a key is what makes this usable in production rather than optional.
+
+```ruby
+# config/application.rb
+config.vpndetection = { api_key: ENV["VPNDETECTION_API_KEY"] }
+```
+
+```ruby
+class HomeController < ApplicationController
+  def index
+    lookup = VPNDetection::Rails.lookup(request)
+    render plain: lookup&.result&.vpn? ? "Hello, VPN user" : "Hello"
+  end
+end
+```
+
+In a non-Rails Rack app, insert it yourself:
+
+```ruby
+use VPNDetection::Rails::Middleware, api_key: ENV["VPNDETECTION_API_KEY"]
+```
+
+By default nothing is blocked. Every request gets an answer and your own code decides what that means — which is usually what you want, because whether a VPN visitor is a problem depends entirely on what they are doing.
+
+## Blocking
+
+Set a `block_condition` and a matching request is answered with `403` and never reaches your controllers.
+
+```ruby
+config.vpndetection = { api_key: ENV["VPNDETECTION_API_KEY"], block_condition: { is_vpn: true } }
+```
+
+A condition is written in the shape of an answer, and only the members you name are considered. That lets it reach the evidence, not just the flags:
+
+```ruby
+{ is_vpn: true, vpn: { provider: "nordvpn" } }         # one provider
+{ is_resproxy: true, resproxy: { hits: { gte: 5 } } }  # a numeric threshold
+{ vpn: { confidence: %w[high medium] } }               # any of these
+[{ is_tor: true }, { is_resproxy: true }]              # a list is OR
+```
+
+Symbol and string keys both work. Values are matched by equality, strings without regard to case. An Array means any-of. A Hash of `gte`/`gt`/`lte`/`lt` compares numbers, and every bound you give must hold, so two of them are a range. Members set to `false` or `nil` are ignored, so a condition states the signals you act on; one that constrains nothing would match every request, and is refused when the middleware is built rather than silently blocking all your traffic.
+
+Replace the refusal with `on_blocked`, which returns a Rack triplet:
+
+```ruby
+on_blocked: ->(request, lookup) { [303, { "location" => "/no-vpn" }, []] }
+```
+
+## Where the client address comes from
+
+This is the setting that decides whether any of the above works, and it is the one thing only you can get right.
+
+**In Rails**, the default reads `env["action_dispatch.remote_ip"]` — the answer `ActionDispatch::RemoteIp` computed from `X-Forwarded-For` minus your `config.action_dispatch.trusted_proxies`. That is the right fix behind a load balancer: tell Rails which proxies are yours and it resolves the visitor for you. `Rack::Request#ip` does *not* read that entry, so reading Rails' own is what makes your `trusted_proxies` mean anything here.
+
+**In a bare Rack app** there is no such entry and the default falls back to `Rack::Request#ip`. Be aware that Rack's `ip` **already trusts `X-Forwarded-For`**: it returns the left-most entry once private and loopback addresses are dropped, which is whatever the caller sent. That is measured, not assumed, and the test suite pins it. Behind nothing, or behind an edge that appends rather than overwrites, name your edge's header instead:
+
+```ruby
+ip_selector: VPNDetection::Rails.header_ip_selector("CF-Connecting-IP")
+```
+
+`VPNDetection::Rails.xff_ip_selector` reads `X-Forwarded-For` directly, and `xff_ip_selector(1)` counts one trusted hop from the right. Anything else, pass your own callable — it receives the Rack request and returns an address.
+
+If the address resolves to a private one, the middleware says so once. That is expected locally and is the signal to fix your configuration anywhere else.
+
+## When a lookup fails
+
+The request is let through, and the reason is on `lookup.error`. Our outage should not become yours, so a network failure, an exhausted quota or a rejected key all fail open. Pass `fail_closed: true` to block instead. Private addresses are answered locally and never fail, so this will not lock you out in development.
+
+## Cost and latency
+
+Answers are cached for an hour, so a returning visitor costs nothing, and private addresses never leave the process. A cache miss is one request to our API, bounded at 2.5 seconds by default and not retried — on a request path, failing open quickly beats holding a visitor while we try again.
+
+Skip what you do not care about:
+
+```ruby
+skip: ->(request) { request.path.start_with?("/assets") }
+```
+
+Beyond a few million distinct visitors a day, stop calling the API per request: [download the dataset](https://vpndetection.io/databases) and look addresses up locally instead.
+
+## Absent is not false
+
+Only `ip` and `is_vpn` come back on every plan. A member your plan does not include is `nil`, which means "not in your plan" rather than "checked, and no" — and Ruby makes that easy to lose, since `nil` and `false` are both falsy.
+
+```ruby
+lookup.result.hosting?            # true or false, never nil
+lookup.result.is_hosting          # nil when your plan does not include it
+lookup.result.included?(:is_hosting)
+```
+
+A `block_condition` naming a member your plan does not serve can never match, so the middleware warns once instead of failing silently. Pass `on_missing_field: :raise` to make it an error.
+
+## Other Libraries
+
+There are official VPNDetection client libraries available for many languages including PHP, Python, Go, Java, Ruby, and many popular frameworks such as Django, Rails, and Laravel. See our GitHub at https://github.com/vpndetection-io for more.
+
+## About VPNDetection
+
+VPN Detection API: Accurate anonymity detection identifying VPNs, residential proxies, hosting servers, Tor nodes, CDNs, relays and more.
+
+[<img src="https://s3.vpndetection.io/vpndetection-public/brand/mark.svg" alt="VPNDetection" width="96"/>](https://vpndetection.io/)
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

data/lib/vpndetection/rails/middleware.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'rack'
+
+module VPNDetection
+  module Rails
+    # Rack middleware that classifies the visitor and optionally refuses the
+    # request.
+    #
+    # Being Rack rather than Rails-specific is deliberate: the same object works
+    # in Sinatra, Hanami, Roda or a bare Rack app, and the Railtie below is only
+    # what saves a Rails user from inserting it by hand.
+    #
+    # Without a `block_condition` this only enriches the request and never
+    # refuses one, leaving the decision to your own controllers. The answer is
+    # on `request.env['vpndetection']`, or `VPNDetection::Rails.lookup(request)`.
+    class Middleware
+      ENV_KEY = 'vpndetection'
+
+      def initialize(app, **options)
+        @app = app
+        @on_blocked = options.delete(:on_blocked) || method(:refuse)
+        @core = VPNDetection::Middleware::Core.new(
+          Rails.default_ip_selector, **options
+        )
+      end
+
+      def call(env)
+        request = ::Rack::Request.new(env)
+        lookup = @core.evaluate(request)
+        return @app.call(env) if lookup.nil?
+
+        env[ENV_KEY] = lookup
+        return @on_blocked.call(request, lookup) if lookup.blocked?
+
+        @app.call(env)
+      end
+
+      private
+
+      def refuse(_request, _lookup)
+        body = JSON.generate({ 'error' => 'access denied' })
+        [403, { 'content-type' => 'application/json' }, [body]]
+      end
+    end
+
+    module_function
+
+    # What the middleware found out about this visitor, or nil when it has not
+    # run for this request or `skip` claimed it.
+    def lookup(request)
+      env = request.respond_to?(:env) ? request.env : request
+      env[Middleware::ENV_KEY]
+    end
+  end
+end

data/lib/vpndetection/rails/railtie.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module VPNDetection
+  module Rails
+    # Inserts the middleware for a Rails app, configured from
+    # `config.vpndetection`.
+    #
+    # Placed before ActionDispatch::Executor so a refusal costs no controller
+    # work, and after Rails' own RemoteIp so `request.ip` already means what
+    # your `trusted_proxies` say it means.
+    class Railtie < ::Rails::Railtie
+      config.vpndetection = ActiveSupport::OrderedOptions.new
+
+      initializer 'vpndetection.middleware' do |app|
+        options = app.config.vpndetection.to_h
+        next if options.delete(:enabled) == false
+
+        app.middleware.insert_after(
+          ActionDispatch::RemoteIp, VPNDetection::Rails::Middleware, **options
+        )
+      end
+    end
+  end
+end

data/lib/vpndetection/rails/selectors.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module VPNDetection
+  module Rails
+    # The client-address selectors, bound to a Rack request.
+    #
+    # There is no portable default, so this is yours to choose - but Rails
+    # already has an answer for the common case, and it is the one to reach for
+    # first.
+    SELECTORS = VPNDetection::Middleware::Selectors.new do |request|
+      VPNDetection::Middleware::RequestView.new(
+        header: ->(name) { request.get_header("HTTP_#{name.upcase.tr('-', '_')}") },
+        framework_ip: -> { framework_ip(request) }
+      )
+    end
+
+    module_function
+
+    # Rails' own answer where there is one, and Rack's otherwise.
+    #
+    # `ActionDispatch::RemoteIp` computes the visitor from `X-Forwarded-For`
+    # minus your `config.action_dispatch.trusted_proxies` and leaves it on
+    # `env['action_dispatch.remote_ip']`. That is the right fix behind a load
+    # balancer, so it is read first - `Rack::Request#ip` does NOT consult it,
+    # and using Rack's alone would silently ignore the trusted_proxies you
+    # configured.
+    #
+    # Outside Rails there is no such entry and this falls back to
+    # `Rack::Request#ip`. **Be aware that Rack's own `ip` already trusts
+    # `X-Forwarded-For`**: it returns the left-most entry after dropping
+    # private and loopback addresses, which is whatever the caller sent.
+    # Measured, not assumed. In a bare Rack app behind nothing, prefer
+    # {.header_ip_selector} or your own.
+    def default_ip_selector
+      SELECTORS.default
+    end
+
+    # @api private
+    def framework_ip(request)
+      # `to_s` because RemoteIp leaves a lazily-resolving object here, not a
+      # String, and a lookup needs the address.
+      rails = request.get_header('action_dispatch.remote_ip')
+      return rails.to_s unless rails.nil?
+
+      request.ip
+    end
+
+    # An address from `X-Forwarded-For`, ignoring Rails' trusted-proxy list.
+    #
+    # The LEFT-MOST entry (depth 0) is whatever the caller sent, because proxies
+    # append to this header. Prefer `trusted_proxies`; reach for this only when
+    # you cannot express your topology there.
+    def xff_ip_selector(depth = 0)
+      SELECTORS.xff(depth)
+    end
+
+    # An address from a single-value header your edge writes -
+    # `header_ip_selector('CF-Connecting-IP')` behind Cloudflare. Falls back to
+    # the Rails accessor when the header is absent.
+    def header_ip_selector(name)
+      SELECTORS.header(name)
+    end
+  end
+end

data/lib/vpndetection/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module VPNDetection
+  module Rails
+    VERSION = '1.0.0'
+  end
+end

data/lib/vpndetection/rails.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'vpndetection'
+require 'vpndetection/middleware'
+
+require_relative 'rails/version'
+require_relative 'rails/selectors'
+require_relative 'rails/middleware'
+require_relative 'rails/railtie' if defined?(::Rails::Railtie)

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: vpndetection-rails
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Mslm Dev
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: vpndetection
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.2.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.2.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+description: Classifies the visitor behind each request - VPN, residential proxy,
+  Tor, hosting, CDN, relay - and hands the answer to your controllers. Rack middleware,
+  so it works in Sinatra, Hanami and Roda too; a Railtie inserts it for you in Rails.
+email:
+- support@vpndetection.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/vpndetection/rails.rb
+- lib/vpndetection/rails/middleware.rb
+- lib/vpndetection/rails/railtie.rb
+- lib/vpndetection/rails/selectors.rb
+- lib/vpndetection/rails/version.rb
+homepage: https://vpndetection.io
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://vpndetection.io
+  source_code_uri: https://github.com/vpndetection-io/sdk-ruby-rails
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Official Rails and Rack middleware for the VPNDetection API.
+test_files: []