reputable 0.1.7 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5ea31e6c135265677697ac1411fb0d9308f6d4454f23a3d1558018eddfccb4a
-  data.tar.gz: 0aea9d057b70a2ca763f5e1f5e6b024d25d07d783feee0447bd311526a189574
+  metadata.gz: e8d9854d3f0dfbf85029fa9411273ffdebad9288eaa11b91649a3aec538b6b2b
+  data.tar.gz: 8d7fbfaf636c06c80a1ea291a773d35c1e478f5dd1261efd6e213a473f1d0362
 SHA512:
-  metadata.gz: f9621074b650d78f8ba44014f5df9880ee8431065f88a9cd6e3da467aef4885da7230851de5cfe316ef3d8162317bd43cba10fd943d87affbbb2ae11046901c9
-  data.tar.gz: 59c4953b9caaf151b3b8a97d057d90b9dab88bdfe71809460a588f35cc8ddc903dacc6805bb9b14ba39d70d203e7622331bbd469e7b870be1da968a8b74b3f77
+  metadata.gz: a13fdb389753a6aed4bde2d9e6bc2304e184db0ded7a579adc6d7fef16d4e1e72a6032f11eec7e6e03e0e706aa2a135c07c17e3e607e227f7670864e84c91aea
+  data.tar.gz: fb215dbd673959e3414eaa31c0a77a3c78366db796f34b1afbef12d066041b1308b0c6312a90dc7ee953a8b578083192509a535fb3bf9b53f265f9f3b9a22f80

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    reputable (0.1.6)
+    reputable (0.1.9)
       connection_pool (~> 2.2)
       redis (>= 4.0, < 6.0)
 

data/README.md

@@ -4,6 +4,8 @@ Ruby gem for integrating with Reputable - bot detection and reputation scoring f
 
 **Resilience First**: This gem is designed to never break your application. All operations fail silently with safe defaults.
 
+Release notes and version bumps: see `clients/ruby/RELEASING.md`.
+
 ## Installation
 
 Add to your Gemfile:
@@ -83,6 +85,11 @@ REPUTABLE_REDIS_URL=rediss://user:password@your-dragonfly.example.com:6379
 # Optional: Base URL for verification and API endpoints (domain only)
 REPUTABLE_BASE_URL=https://api.reputable.click
 
+# Optional: Blocked page branding/support info
+REPUTABLE_SITE_NAME="Example Store"
+REPUTABLE_SUPPORT_EMAIL=support@example.com
+REPUTABLE_SUPPORT_URL=https://example.com/support
+
 # Optional: Disable entirely (useful for test environments)
 REPUTABLE_ENABLED=false
 
@@ -142,6 +149,11 @@ Reputable.configure do |config|
   # Supports comma-separated list in REPUTABLE_TRUSTED_KEYS or single key in REPUTABLE_TRUSTED_KEY
   config.trusted_keys = ENV['REPUTABLE_TRUSTED_KEYS']&.split(',') || ENV['REPUTABLE_TRUSTED_KEY']
   config.base_url = ENV['REPUTABLE_BASE_URL'] # Domain only
+
+  # Optional: blocked page branding/support info
+  config.site_name = ENV['REPUTABLE_SITE_NAME']
+  config.support_email = ENV['REPUTABLE_SUPPORT_EMAIL']
+  config.support_url = ENV['REPUTABLE_SUPPORT_URL']
   
   # Error callback (optional)
   config.on_error = ->(error, context) {
@@ -260,6 +272,27 @@ config.middleware.use Reputable::Middleware,
   async: true
 ```
 
+### Optional Reputation Gate
+
+If you want the middleware to enforce IP reputation decisions, enable the gate:
+
+```ruby
+config.middleware.use Reputable::Middleware,
+  reputation_gate: true,
+  challenge_action: :verify,      # Redirect to verification for untrusted_challenge
+  block_action: :blocked_page_remote, # Redirect to hosted blocked page (uses app UI settings)
+  blocked_page_path: "/_reputable/blocked" # Only used for local blocked page
+```
+
+Notes:
+- For `untrusted_challenge`, the middleware redirects to the Reputable verification URL.
+- For `untrusted_block`, the default is to redirect to the hosted blocked page (`/_reputable/verify/blocked`).
+- The hosted blocked page uses the same app UI settings as the verify/failure pages (`siteName`, `supportEmail`).
+- To render a local blocked page instead, set `block_action: :blocked_page` and pass `blocked_page` options.
+- To use a custom hosted page, set `blocked_redirect_url: "https://example.com/blocked"`.
+- Use `blocked_page_path` only for local blocked pages (or to build a custom `failure_url`).
+- Override `challenge_redirect_status` (default `302`) or `verification_force_challenge` if needed.
+
 ### Default Skipped Paths
 
 The middleware automatically skips:
@@ -305,6 +338,56 @@ rep = current_ip_reputation
 # => { status: 'trusted_verified', reason: 'payment', ... }
 ```
 
+### Verification Redirect Helpers
+
+```ruby
+class SessionsController < ApplicationController
+  def new
+    require_reputable_verification!
+    # If verified, continue
+  end
+end
+```
+
+Optional args:
+- `return_url` (default: `request.original_url`)
+- `failure_url` (default: API `/verify/failure` page)
+- `session_id` (default: `session.id`)
+- `force_challenge` (default: `false`)
+- `session_key` (default: `:reputable_verified_at`)
+
+You can check or clear the session flag:
+
+```ruby
+reputable_verified?
+clear_reputable_verification!
+```
+
+### Reputation Gate Helpers
+
+```ruby
+class SessionsController < ApplicationController
+  def new
+    require_reputable_reputation!
+    # If not blocked/challenged, continue
+  end
+end
+```
+
+`require_reputable_reputation!` will:
+- Render a blocked page for `untrusted_block`
+- Run verification flow for `untrusted_challenge`
+
+You can also render the blocked page directly:
+
+```ruby
+render_reputable_blocked_page(
+  site_name: "Example Store",
+  support_email: "support@example.com",
+  support_url: "https://example.com/support"
+)
+```
+
 ---
 
 ## Manual API Usage
@@ -391,7 +474,7 @@ end
 
 **Options:**
 - `return_url` (required): Where to redirect after successful verification
-- `failure_url` (optional): Where to redirect on failure (defaults to return_url)
+- `failure_url` (optional): Where to redirect on failure (defaults to API `/verify/failure` page)
 - `session_id` (optional): Bind verification to a specific session
 - `force_challenge` (optional): If `true`, always show CAPTCHA even for trusted users. Useful for testing the challenge flow.
 

data/lib/reputable/configuration.rb

@@ -14,7 +14,8 @@ module Reputable
                   :default_ttls, :pool_size, :pool_timeout,
                   :connect_timeout, :read_timeout, :write_timeout,
                   :ssl_params, :trusted_proxies, :ip_header_priority,
-                  :on_error, :trusted_keys, :base_url
+                  :on_error, :trusted_keys, :base_url,
+                  :site_name, :support_email, :support_url
 
     # Alias for backward compatibility
     alias_method :verification_base_url, :base_url
@@ -78,6 +79,9 @@ module Reputable
         @trusted_keys = [ENV["REPUTABLE_SECRET_KEY"]]
       end
       @base_url = ENV.fetch("REPUTABLE_BASE_URL", "https://api.reputable.click")
+      @site_name = ENV["REPUTABLE_SITE_NAME"]
+      @support_email = ENV["REPUTABLE_SUPPORT_EMAIL"]
+      @support_url = ENV["REPUTABLE_SUPPORT_URL"]
     end
 
     # Alias for backward compatibility

data/lib/reputable/middleware.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "blocked_page"
+
 module Reputable
   # Rack middleware for automatic request tracking
   #
@@ -42,12 +44,34 @@ module Reputable
       @skip_if = options[:skip_if]
       @tag_builder = options[:tag_builder]
       @async = options.fetch(:async, true)
+      @reputation_gate = options.fetch(:reputation_gate, false)
+      @challenge_action = options.fetch(:challenge_action, :verify)
+      @block_action = options.fetch(:block_action, :blocked_page_remote)
+      @challenge_redirect_status = options.fetch(:challenge_redirect_status, 302)
+      @blocked_redirect_status = options.fetch(:blocked_redirect_status, 302)
+      @blocked_redirect_url = options[:blocked_redirect_url]
+      @verification_force_challenge = options.fetch(:verification_force_challenge, false)
+      @verification_failure_url = options[:verification_failure_url]
+      @verification_session_id = options[:verification_session_id]
+      @verified_session_keys = Array(options.fetch(:verified_session_keys, [:reputable_verified_at, :reputable_verified]))
+      @blocked_page_options = options.fetch(:blocked_page, {})
+      @blocked_page_path = options[:blocked_page_path]
     end
 
     def call(env)
       # Check for verification return parameters and verify signature if present
       handle_verification_return(env)
 
+      # Optional: render blocked page path directly
+      if (blocked_response = handle_blocked_page_request(env))
+        return blocked_response
+      end
+
+      # Optional: enforce reputation gate before app
+      if (gate_response = safe_reputation_gate(env))
+        return gate_response
+      end
+
       # ALWAYS process the request first - tracking must never block
       status, headers, response = @app.call(env)
 
@@ -60,6 +84,33 @@ module Reputable
 
     private
 
+    def safe_reputation_gate(env)
+      return nil unless @reputation_gate
+      return nil unless Reputable.enabled?
+      return nil if skip_request?(env)
+
+      enforce_reputation_gate(env)
+    rescue StandardError => e
+      Reputable.logger&.debug("Reputable reputation gate: #{e.class} - #{e.message}")
+      nil
+    end
+
+    def enforce_reputation_gate(env)
+      ip = extract_ip(env)
+      status = Reputable::Reputation.lookup_ip(ip)
+      return nil if status.nil?
+
+      case status
+      when "untrusted_block"
+        handle_block_action(env, ip)
+      when "untrusted_challenge"
+        return nil if verified_session?(env)
+        handle_challenge_action(env)
+      else
+        nil
+      end
+    end
+
     def safe_track_request(env)
       # Skip if disabled globally
       return unless Reputable.enabled?
@@ -93,6 +144,145 @@ module Reputable
       Reputable.logger&.debug("Reputable verification error: #{e.message}")
     end
 
+    def handle_blocked_page_request(env)
+      return nil unless @blocked_page_path
+
+      path = env["PATH_INFO"] || "/"
+      return nil unless path == @blocked_page_path
+
+      ip = extract_ip(env)
+      build_blocked_page_response(ip)
+    rescue StandardError => e
+      Reputable.logger&.debug("Reputable blocked page: #{e.class} - #{e.message}")
+      nil
+    end
+
+    def handle_block_action(env, ip)
+      case @block_action
+      when :blocked_page
+        build_blocked_page_response(ip)
+      when :blocked_page_remote
+        url = resolve_blocked_redirect_url(env) || Reputable.blocked_page_url
+        redirect_response(url, @blocked_redirect_status)
+      when :forbidden
+        [403, { "Content-Type" => "text/plain; charset=utf-8" }, ["Forbidden"]]
+      when Proc
+        @block_action.call(env, ip)
+      else
+        build_blocked_page_response(ip)
+      end
+    end
+
+    def handle_challenge_action(env)
+      case @challenge_action
+      when :verify
+        keys = Reputable.configuration.trusted_keys
+        return nil if keys.nil? || keys.empty?
+
+        request = Rack::Request.new(env)
+        return_url = request.url
+        failure_url = build_verification_failure_url(request)
+        session_id = resolve_session_id(env)
+
+        redirect_url = Reputable.verification_url(
+          return_url: return_url,
+          failure_url: failure_url,
+          session_id: session_id,
+          force_challenge: @verification_force_challenge
+        )
+
+        return nil if redirect_url == return_url
+
+        redirect_response(redirect_url, @challenge_redirect_status)
+      when Proc
+        @challenge_action.call(env)
+      else
+        nil
+      end
+    end
+
+    def build_verification_failure_url(request)
+      if @verification_failure_url.respond_to?(:call)
+        @verification_failure_url.call(request)
+      elsif @verification_failure_url
+        @verification_failure_url
+      elsif @blocked_page_path
+        base = request.base_url
+        path = @blocked_page_path.start_with?("/") ? @blocked_page_path : "/#{@blocked_page_path}"
+        "#{base}#{path}"
+      end
+    rescue StandardError
+      nil
+    end
+
+    def resolve_session_id(env)
+      return @verification_session_id.call(env) if @verification_session_id.respond_to?(:call)
+      return @verification_session_id if @verification_session_id.is_a?(String)
+
+      if @verification_session_id.is_a?(Symbol)
+        session = env["rack.session"]
+        return session[@verification_session_id] if session
+      end
+
+      session = env["rack.session"]
+      return nil unless session
+
+      return session.id if session.respond_to?(:id) && session.id
+
+      options = env["rack.session.options"]
+      return options[:id] if options.is_a?(Hash) && options[:id]
+
+      session[:session_id] || session["session_id"]
+    rescue StandardError
+      nil
+    end
+
+    def verified_session?(env)
+      return true if env["reputable.verified"]
+
+      session = env["rack.session"]
+      return false unless session
+
+      @verified_session_keys.any? do |key|
+        session[key] || session[key.to_s]
+      end
+    rescue StandardError
+      false
+    end
+
+    def build_blocked_page_response(client_ip)
+      options = blocked_page_options.merge(client_ip: client_ip)
+      Reputable::BlockedPage.response(**options)
+    end
+
+    def blocked_page_options
+      config = Reputable.configuration
+      defaults = {
+        site_name: config.site_name,
+        support_email: config.support_email,
+        support_url: config.support_url
+      }
+      defaults.merge(@blocked_page_options)
+    end
+
+    def redirect_response(url, status)
+      headers = {
+        "Location" => url,
+        "Content-Type" => "text/html; charset=utf-8",
+        "Cache-Control" => "no-store"
+      }
+      [status, headers, ["Redirecting to verification..."]]
+    end
+
+    def resolve_blocked_redirect_url(env)
+      return @blocked_redirect_url.call(env) if @blocked_redirect_url.respond_to?(:call)
+      return @blocked_redirect_url if @blocked_redirect_url.is_a?(String)
+
+      nil
+    rescue StandardError
+      nil
+    end
+
     def skip_request?(env)
       return true if @skip_if&.call(env)
 

data/lib/reputable/rails.rb

@@ -7,6 +7,10 @@ module Reputable
     module ControllerHelpers
       extend ActiveSupport::Concern
 
+      included do
+        helper_method :reputable_verified? if respond_to?(:helper_method)
+      end
+
       # Track the current request with optional extra tags
       def track_reputable_request(tags: [], **options)
         Reputable::Tracker.track_request(
@@ -81,6 +85,139 @@ module Reputable
       def current_ip_status
         Reputable::Reputation.lookup_ip(request.remote_ip)
       end
+
+      # ========================================
+      # Verification redirect helpers
+      # ========================================
+
+      # Render the standard blocked page
+      def render_reputable_blocked_page(
+        status: 403,
+        site_name: nil,
+        support_email: nil,
+        support_url: nil,
+        heading: "Access blocked",
+        message: nil,
+        show_ip: true
+      )
+        config = Reputable.configuration
+        html = Reputable::BlockedPage.html(
+          site_name: site_name || config.site_name,
+          support_email: support_email || config.support_email,
+          support_url: support_url || config.support_url,
+          client_ip: request.remote_ip,
+          heading: heading,
+          message: message,
+          show_ip: show_ip
+        )
+
+        render html: html.html_safe, status: status, content_type: "text/html"
+      end
+
+      # Check if the current session has already passed verification
+      # @param session_key [Symbol]
+      # @return [Boolean]
+      def reputable_verified?(session_key: :reputable_verified_at)
+        session[session_key].present?
+      end
+
+      # Clear verification status for the current session
+      # @param session_key [Symbol]
+      def clear_reputable_verification!(session_key: :reputable_verified_at)
+        session.delete(session_key)
+      end
+
+      # Enforce verification redirect flow.
+      # - If already verified in this session, returns immediately.
+      # - If returning with signature, validates and marks session.
+      # - Otherwise redirects to verification URL.
+      #
+      # @param return_url [String] URL to return to after verification
+      # @param failure_url [String] URL to return to on failure/invalid token
+      # @param session_id [String] Optional session id to link
+      # @param force_challenge [Boolean] Force challenge even if trusted
+      # @param session_key [Symbol] Session key used to store verified state
+      def require_reputable_verification!(
+        return_url: request.original_url,
+        failure_url: nil,
+        session_id: session.id,
+        force_challenge: false,
+        session_key: :reputable_verified_at
+      )
+        return if reputable_verified?(session_key: session_key)
+
+        if params[:reputable_signature]
+          if Reputable.verify_redirect_return(params)
+            if params[:reputable_status] == "pass"
+              session[session_key] = Time.now.to_i
+              return
+            end
+
+            redirect_to failure_url and return
+          else
+            render plain: "Verification failed", status: 403 and return
+          end
+        end
+
+        redirect_to reputable_verification_url(
+          return_url: return_url,
+          failure_url: failure_url,
+          session_id: session_id,
+          force_challenge: force_challenge
+        ) and return
+      end
+
+      # Enforce reputation-based access control.
+      # - If IP is blocked, render a blocked page.
+      # - If IP is challenged, run verification flow.
+      def require_reputable_reputation!(
+        return_url: request.original_url,
+        failure_url: nil,
+        session_id: session.id,
+        force_challenge: false,
+        session_key: :reputable_verified_at,
+        blocked_status: 403,
+        blocked_site_name: nil,
+        blocked_support_email: nil,
+        blocked_support_url: nil,
+        blocked_heading: "Access blocked",
+        blocked_message: nil,
+        blocked_show_ip: true
+      )
+        if current_ip_blocked?
+          render_reputable_blocked_page(
+            status: blocked_status,
+            site_name: blocked_site_name,
+            support_email: blocked_support_email,
+            support_url: blocked_support_url,
+            heading: blocked_heading,
+            message: blocked_message,
+            show_ip: blocked_show_ip
+          )
+          return
+        end
+
+        return unless current_ip_challenged?
+
+        require_reputable_verification!(
+          return_url: return_url,
+          failure_url: failure_url,
+          session_id: session_id,
+          force_challenge: force_challenge,
+          session_key: session_key
+        )
+      end
+
+      private
+
+      def reputable_verification_url(return_url:, failure_url:, session_id:, force_challenge:)
+        Reputable.verification_url(
+          return_url: return_url,
+          failure_url: failure_url,
+          session_id: session_id,
+          force_challenge: force_challenge
+        )
+      end
     end
 
     # Railtie for automatic Rails integration (only defined when Rails is present)

data/lib/reputable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Reputable
-  VERSION = "0.1.7"
+  VERSION = "0.1.9"
 end

data/lib/reputable.rb

@@ -7,6 +7,7 @@ require_relative "reputable/configuration"
 require_relative "reputable/connection"
 require_relative "reputable/tracker"
 require_relative "reputable/reputation"
+require_relative "reputable/blocked_page"
 require_relative "reputable/middleware"
 
 # Optional Rails integration (only load if Rails is defined)
@@ -145,6 +146,7 @@ module Reputable
       # Ensure base_url doesn't have a trailing slash, then append the verify path
       base_url = base_url.chomp("/")
       verify_url = "#{base_url}/_reputable/verify"
+      failure_url ||= "#{base_url}/_reputable/verify/failure"
 
       # JWT Header
       header = { alg: "HS256", typ: "JWT" }
@@ -170,6 +172,14 @@ module Reputable
       "#{verify_url}?token=#{token}"
     end
 
+    # Build the hosted blocked page URL
+    # @return [String]
+    def blocked_page_url
+      base_url = configuration.base_url
+      base_url = base_url.chomp("/")
+      "#{base_url}/_reputable/verify/blocked"
+    end
+
     # Verify the signature of a redirect return
     # @param params [Hash] Request query parameters
     # @return [Boolean] true if valid logic and passed signature check

data/reputable.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "lib/reputable/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "reputable"
+  spec.version = Reputable::VERSION
+  spec.authors = ["Reputable"]
+  spec.email = ["support@reputable.click"]
+
+  spec.summary = "Ruby client for Reputable - bot detection and reputation scoring"
+  spec.description = "Track requests and manage IP reputation through Redis/Dragonfly integration with Reputable"
+  spec.homepage = "https://github.com/reputable-click/reputable-rb"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)}) || f.end_with?(".gem")
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "redis", ">= 4.0", "< 6.0"
+  spec.add_dependency "connection_pool", "~> 2.2"
+
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "rack", "~> 2.0"
+  spec.add_development_dependency "rubocop", "~> 1.0"
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: reputable
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.9
 platform: ruby
 authors:
 - Reputable
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-12-28 00:00:00.000000000 Z
+date: 2025-12-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -135,6 +135,7 @@ files:
 - lib/reputable/reputation.rb
 - lib/reputable/tracker.rb
 - lib/reputable/version.rb
+- reputable.gemspec
 homepage: https://github.com/reputable-click/reputable-rb
 licenses:
 - MIT