reputable 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58cd625b57ec78df69ca3a6f46e810f3870d30d2c708c61ded9c028737eef1e8
-  data.tar.gz: b73a0ad0cfffead0089d870bfd51dee53b3ee4af4305992ec9285f37f0e18e4b
+  metadata.gz: ca78832e420ad0cacad0c44bbfbf2a682f1b9f702bbaf8aa07a44e4e04d7d53b
+  data.tar.gz: 9e15f534984a4e3d67560a98cbede0c596d02d30fb7f7171b380b043b0781384
 SHA512:
-  metadata.gz: 8e99d9b81e8fe4ee5594ad30637eac3387a89e4073644ae8a54a25c211e6c2a0cae9dcf38b03a6767474845f0b63437e719a2f9bc4748b208afe617c3d43a9e5
-  data.tar.gz: 5e6e0d1a50150f7e5acec89be721be877ee17e1a1bb9f388c5ab4c70b14e9b2a6efcd816087e4a177e712723081550d7af704cc8f212961131f92cfdc8063de8
+  metadata.gz: 23832e31d409bb3316c33c931e6207f24eb2ea078c2fa79d3d0c4618e4ffd3359f525d0c6b090344bb5d8e79cf9fdc714752ae09180ce973dd353d93015afb6c
+  data.tar.gz: 9eb4a989b111a493e7555672057946c2928251a1112e7b75e011bf7183c329ee3b9c6c6cb0e34a163d3803cb5956321b443b25f2d9fcbfca5c90ad16b73cd766

data/Gemfile.lock

@@ -0,0 +1,76 @@
+PATH
+  remote: .
+  specs:
+    reputable (0.1.3)
+      connection_pool (~> 2.2)
+      redis (>= 4.0, < 6.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    connection_pool (2.5.5)
+    diff-lcs (1.6.2)
+    json (2.18.0)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    parallel (1.27.0)
+    parser (3.3.10.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.7.0)
+    racc (1.8.1)
+    rack (2.2.21)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    redis (5.4.1)
+      redis-client (>= 0.22.0)
+    redis-client (0.26.2)
+      connection_pool
+    regexp_parser (2.11.3)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.7)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.6)
+    rubocop (1.82.0)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.48.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.48.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  bundler (~> 2.0)
+  rack (~> 2.0)
+  rake (~> 13.0)
+  reputable!
+  rspec (~> 3.0)
+  rubocop (~> 1.21)
+
+BUNDLED WITH
+   2.5.9

data/README.md

@@ -28,9 +28,6 @@ Reputable.configure do |config|
   # Required: Redis/Dragonfly URL (TLS supported via rediss://)
   config.redis_url = ENV['REPUTABLE_REDIS_URL']
   
-  # Required: Your tenant ID
-  config.tenant_id = ENV['REPUTABLE_TENANT_ID']
-  
   # Optional: Enable logging (logs at debug level)
   Reputable.logger = Rails.logger
 end
@@ -82,7 +79,6 @@ All configuration can be set via environment variables:
 ```bash
 # Required
 REPUTABLE_REDIS_URL=rediss://user:password@your-dragonfly.example.com:6379
-REPUTABLE_TENANT_ID=your-tenant-id
 
 # Optional: Disable entirely (useful for test environments)
 REPUTABLE_ENABLED=false
@@ -105,9 +101,6 @@ Reputable.configure do |config|
   # Redis connection (supports redis:// and rediss:// for TLS)
   config.redis_url = ENV['REPUTABLE_REDIS_URL']
   
-  # Your tenant identifier
-  config.tenant_id = ENV['REPUTABLE_TENANT_ID']
-  
   # Connection pool settings
   config.pool_size = 5           # Number of Redis connections
   config.pool_timeout = 1.0      # Max wait for connection (seconds)
@@ -142,6 +135,11 @@ Reputable.configure do |config|
     REMOTE_ADDR
   ]
   
+  # Verification Configuration
+  # 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.verification_base_url = ENV['REPUTABLE_VERIFY_URL']     # URL of your Reputable API verify endpoint
+  
   # Error callback (optional)
   config.on_error = ->(error, context) {
     # Report to your error tracking service
@@ -284,8 +282,6 @@ track_reputable_request(tags: ['custom:tag'])
 
 # Trust methods (after successful actions)
 trust_current_ip(reason: 'payment_completed', order_id: '123')
-trust_current_user(reason: 'email_verified')
-trust_current_session(reason: 'captcha_passed')
 
 # Challenge/Block methods
 challenge_current_ip(reason: 'suspicious_activity')
@@ -319,11 +315,9 @@ Reputable.track_request(
   path: request.path,
   query: request.query_string,
   method: request.request_method,
-  session_id: session.id,
-  session_present: true,
   user_agent: request.user_agent,
   referer: request.referer,
-  tags: ['ctx:page:product']
+  tags: ['view:page:product']
 )
 
 # Asynchronous (fire-and-forget, recommended)
@@ -339,12 +333,6 @@ Reputable.track_request_async(
 # Trust IP forever (after payment, verification, etc.)
 Reputable.trust_ip(request.ip, reason: 'payment_completed', order_id: order.id)
 
-# Trust a user
-Reputable.trust_user(current_user.id, reason: 'email_verified')
-
-# Trust a session (default: 24 hour TTL)
-Reputable.trust_session(session.id, reason: 'captcha_passed')
-
 # Challenge (require CAPTCHA, etc.)
 Reputable.challenge_ip(request.ip, reason: 'unusual_activity')
 
@@ -372,12 +360,80 @@ Reputable.lookup_reputation(:ip, request.ip)
 # => { status: "trusted_verified", reason: "payment_completed", 
 #      source: "app_server", updated_at: 1703123456789, 
 #      expires_at: 0, metadata: { order_id: "123" } }
+```
+
+---
+
+## User Verification & Trust Flow
+
+When you identify a suspicious user (e.g., high risk score or specific tag), you can redirect them to the Reputable verification page. This page performs advanced browser checks and challenges (CAPTCHA) if necessary.
+
+### 1. Generating a Signed Redirect URL
+
+To effectively hand off verification handling to Reputable, generate a signed verification URL:
+
+```ruby
+# In your controller
+if suspicious_activity_detected?
+  redirect_url = Reputable.verification_url(
+    return_url: request.original_url, # Where to send them back after verification
+    failure_url: root_url,            # Optional: where to send if they fail/garbage token
+    session_id: session.id            # Optional: link specific session
+  )
+  
+  redirect_to redirect_url
+end
+```
+
+### 2. Handling the Return Redirect
+
+When the user passes verification (or is determined to be already trusted/clean), they are immediately redirected back to your `return_url` with signed parameters.
+
+**Middleware (Automatic Handling):**
+If you are using `Reputable::Middleware` (recommended), this is handled automatically. The middleware detects the return parameters, verifies the signature, and sets `env['reputable.verified'] = true`.
+
+```ruby
+# In your controller
+if request.env['reputable.verified']
+  # User just passed verification!
+  # You might want to graduate them to trusted status locally
+  trust_current_ip(reason: 'interactive_verification')
+end
+```
 
-# User/Session lookups
-Reputable.trusted_user?(current_user.id)
-Reputable.trusted_session?(session.id)
+**Manual Verification:**
+If you need to verify manually (e.g., custom controller logic):
+
+```ruby
+# In your controller action (the return_url target)
+if params[:reputable_signature]
+  if Reputable.verify_redirect_return(params)
+    # Signature is VALID. Meaning Reputable actually sent this user back.
+    
+    # Inspect outcomes
+    status = params[:reputable_status]   # 'pass', 'fail'
+    outcome = params[:reputable_outcome] # 'trusted_verified', 'trusted_behavior', 'unknown'
+    country = params[:reputable_country] # 'US', 'DE', etc.
+    
+    if status == 'pass'
+      # Grant access
+    end
+  else
+    # Invalid signature - potential tampering attempt!
+    render plain: "Verification failed", status: 403
+  end
+end
 ```
 
+**Return Parameters:**
+The return URL will contain:
+- `reputable_status`: `pass` or `fail`
+- `reputable_session_id`: The session ID you provided
+- `reputable_outcome`: The specific reputation outcome (e.g., `trusted_verified`)
+- `reputable_ignore_analytics`: 'true'/'false' flag
+- `reputable_country`: ISO country code
+- `reputable_signature`: HMAC-SHA256 signature of the above
+
 ---
 
 ## Resilience & Failsafe Features
@@ -438,10 +494,10 @@ Use tags to classify requests for behavioral analysis:
 
 ```ruby
 # Page context
-tags: ['ctx:page:product']
-tags: ['ctx:page:checkout']
-tags: ['ctx:page:cart']
-tags: ['ctx:page:login']
+tags: ['view:page:product']
+tags: ['view:page:checkout']
+tags: ['view:page:cart']
+tags: ['view:page:login']
 
 # Traffic source
 tags: ['trust:channel:email']
@@ -493,7 +549,6 @@ expect(Reputable.lookup_ip('1.2.3.4')).to be_nil
 ### What's Available from Rails
 
 - IP reputation and history
-- Session tracking
 - Request classification
 - UA churn detection
 - Cross-request pattern analysis

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/reputable/configuration.rb

@@ -9,12 +9,12 @@ module Reputable
   # Supports TLS connections with automatic SSL error handling.
   # All SSL/connection errors are caught and logged, never breaking your app.
   class Configuration
-    attr_accessor :redis_url, :redis_options, :tenant_id, :buffer_prefix,
+    attr_accessor :redis_url, :redis_options, :buffer_prefix,
                   :request_buffer_key, :reputation_buffer_key,
                   :default_ttls, :pool_size, :pool_timeout,
                   :connect_timeout, :read_timeout, :write_timeout,
                   :ssl_params, :trusted_proxies, :ip_header_priority,
-                  :on_error
+                  :on_error, :trusted_keys, :verification_base_url
 
     # Default TTLs in seconds (0 = forever)
     DEFAULT_TTLS = {
@@ -52,7 +52,6 @@ module Reputable
     def initialize
       @redis_url = ENV.fetch("REPUTABLE_REDIS_URL", "redis://127.0.0.1:6379")
       @redis_options = {}
-      @tenant_id = ENV.fetch("REPUTABLE_TENANT_ID", "default")
       @buffer_prefix = "reputable:buffer"
       @pool_size = Integer(ENV.fetch("REPUTABLE_POOL_SIZE", "5"))
       @pool_timeout = Float(ENV.fetch("REPUTABLE_POOL_TIMEOUT", "1.0"))
@@ -64,6 +63,34 @@ module Reputable
       @trusted_proxies = nil  # Additional trusted proxy IPs/ranges
       @ip_header_priority = DEFAULT_IP_HEADERS.dup
       @on_error = nil  # Optional error callback: ->(error, context) { ... }
+      
+      # Support multiple trusted keys (comma-separated), fallback to old secret key env var
+      @trusted_keys = []
+      if ENV["REPUTABLE_TRUSTED_KEYS"]
+        @trusted_keys = ENV["REPUTABLE_TRUSTED_KEYS"].split(",").map(&:strip)
+      elsif ENV["REPUTABLE_TRUSTED_KEY"]
+        @trusted_keys = [ENV["REPUTABLE_TRUSTED_KEY"]]
+      elsif ENV["REPUTABLE_SECRET_KEY"]
+        @trusted_keys = [ENV["REPUTABLE_SECRET_KEY"]]
+      end
+      @verification_base_url = ENV.fetch("REPUTABLE_VERIFY_URL", "https://api.reputable.click/_reputable/verify")
+    end
+
+    # Alias for backward compatibility
+    def secret_key
+      @trusted_keys.first
+    end
+
+    def secret_key=(key)
+      @trusted_keys = [key]
+    end
+
+    def trusted_keys=(keys)
+      @trusted_keys = Array(keys)
+    end
+
+    def trusted_keys
+      @trusted_keys
     end
 
     # Check if Reputable is enabled (can be disabled via ENV)
@@ -75,11 +102,11 @@ module Reputable
     end
 
     def request_buffer_key
-      @request_buffer_key || "#{buffer_prefix}:requests:#{tenant_id}"
+      @request_buffer_key || "#{buffer_prefix}:requests"
     end
 
     def reputation_buffer_key
-      @reputation_buffer_key || "#{buffer_prefix}:reputation:#{tenant_id}"
+      @reputation_buffer_key || "#{buffer_prefix}:reputation"
     end
 
     def default_ttl_for(status)

data/lib/reputable/middleware.rb

@@ -45,6 +45,9 @@ module Reputable
     end
 
     def call(env)
+      # Check for verification return parameters and verify signature if present
+      handle_verification_return(env)
+
       # ALWAYS process the request first - tracking must never block
       status, headers, response = @app.call(env)
 
@@ -70,6 +73,26 @@ module Reputable
       Reputable.logger&.debug("Reputable middleware: #{e.class} - #{e.message}")
     end
 
+    def handle_verification_return(env)
+      request = Rack::Request.new(env)
+      # Quick check to avoid overhead
+      return unless request.query_string.include?("reputable_status")
+      
+      return unless request.params["reputable_status"] == "pass"
+
+      if Reputable.verify_redirect_return(request.params)
+        env["reputable.verified"] = true
+        
+        # Store in session if available
+        if env["rack.session"]
+          env["rack.session"]["reputable_verified"] = true
+          env["rack.session"]["reputable_verified_at"] = Time.now.to_i
+        end
+      end
+    rescue StandardError => e
+      Reputable.logger&.debug("Reputable verification error: #{e.message}")
+    end
+
     def skip_request?(env)
       return true if @skip_if&.call(env)
 
@@ -109,8 +132,6 @@ module Reputable
         path: request.path,
         query: request.query_string.empty? ? nil : request.query_string,
         method: request.request_method,
-        session_id: extract_session_id(env),
-        session_present: session_present?(env),
         user_agent: env["HTTP_USER_AGENT"],
         referer: env["HTTP_REFERER"],
         tags: build_tags(env)
@@ -190,29 +211,6 @@ module Reputable
       nil
     end
 
-    def extract_session_id(env)
-      # Try rack.session.id first
-      return env["rack.session.id"] if env["rack.session.id"]
-
-      # Try to get from rack.session
-      session = env["rack.session"]
-      return session.id.to_s if session.respond_to?(:id)
-
-      nil
-    rescue StandardError
-      nil
-    end
-
-    def session_present?(env)
-      return true if env["rack.session.id"]
-      return true if env["rack.session"]&.any?
-      return true if env["HTTP_COOKIE"]&.include?("_session")
-
-      false
-    rescue StandardError
-      false
-    end
-
     def build_tags(env)
       tags = []
 

data/lib/reputable/rails.rb

@@ -14,8 +14,6 @@ module Reputable
           path: request.path,
           query: request.query_string,
           method: request.method,
-          session_id: session.id.to_s,
-          session_present: session.any?,
           user_agent: request.user_agent,
           referer: request.referer,
           tags: tags,
@@ -32,26 +30,6 @@ module Reputable
         )
       end
 
-      # Trust the current user
-      def trust_current_user(reason:, **metadata)
-        return false unless respond_to?(:current_user) && current_user
-
-        Reputable::Reputation.trust_user(
-          current_user.id,
-          reason: reason,
-          **metadata
-        )
-      end
-
-      # Trust the current session
-      def trust_current_session(reason:, **metadata)
-        Reputable::Reputation.trust_session(
-          session.id.to_s,
-          reason: reason,
-          **metadata
-        )
-      end
-
       # Challenge the current IP
       def challenge_current_ip(reason:, **metadata)
         Reputable::Reputation.challenge_ip(
@@ -103,20 +81,6 @@ module Reputable
       def current_ip_status
         Reputable::Reputation.lookup_ip(request.remote_ip)
       end
-
-      # Check if current user is trusted
-      # @return [Boolean]
-      def current_user_trusted?
-        return false unless respond_to?(:current_user) && current_user
-        
-        Reputable::Reputation.trusted_user?(current_user.id)
-      end
-
-      # Check if current session is trusted
-      # @return [Boolean]
-      def current_session_trusted?
-        Reputable::Reputation.trusted_session?(session.id.to_s)
-      end
     end
 
     # Railtie for automatic Rails integration (only defined when Rails is present)
@@ -130,7 +94,6 @@ module Reputable
               creds = ::Rails.application.credentials.reputable rescue nil
               if creds
                 config.redis_url = creds[:redis_url] if creds[:redis_url]
-                config.tenant_id = creds[:tenant_id] if creds[:tenant_id]
               end
             end
           end

data/lib/reputable/reputation.rb

@@ -19,12 +19,12 @@ module Reputable
       untrusted_ignore
     ].freeze
 
-    VALID_ENTITY_TYPES = %i[ip asn ja4 session user].freeze
+    VALID_ENTITY_TYPES = %i[ip asn ja4].freeze
 
     class << self
       # Apply a reputation status to an entity
       #
-      # @param entity_type [Symbol] Type of entity (:ip, :asn, :ja4, :session, :user)
+      # @param entity_type [Symbol] Type of entity (:ip, :asn, :ja4)
       # @param entity_id [String] The entity identifier (IP address, ASN, etc.)
       # @param status [Symbol] Reputation status to apply
       # @param options [Hash] Additional options
@@ -110,30 +110,6 @@ module Reputable
         )
       end
 
-      # Trust a user (by internal user ID)
-      def trust_user(user_id, reason: "verified_user", **metadata)
-        apply(
-          entity_type: :user,
-          entity_id: user_id.to_s,
-          status: :trusted_verified,
-          reason: reason,
-          ttl: 0,
-          metadata: metadata
-        )
-      end
-
-      # Trust a session
-      def trust_session(session_id, reason: "verified_session", ttl: nil, **metadata)
-        apply(
-          entity_type: :session,
-          entity_id: session_id,
-          status: :trusted_verified,
-          reason: reason,
-          ttl: ttl || (24 * 3600), # Default 24 hours for sessions
-          metadata: metadata
-        )
-      end
-
       # ========================================================================
       # LOOKUP METHODS (O(1) Redis hash lookups)
       # ========================================================================
@@ -141,7 +117,7 @@ module Reputable
       # Lookup the current reputation status for an entity
       # This is an O(1) Redis HGETALL operation
       #
-      # @param entity_type [Symbol] Type of entity (:ip, :asn, :ja4, :session, :user)
+      # @param entity_type [Symbol] Type of entity (:ip, :asn, :ja4)
       # @param entity_id [String] The entity identifier
       # @return [Hash, nil] Reputation data or nil if not found/expired/error
       #
@@ -227,42 +203,6 @@ module Reputable
         lookup_ip(ip) == "untrusted_challenge"
       end
 
-      # Lookup user reputation
-      #
-      # @param user_id [String, Integer] User ID
-      # @return [String, nil] Status string or nil
-      def lookup_user(user_id)
-        result = lookup(:user, user_id.to_s)
-        result&.dig(:status)
-      end
-
-      # Check if a user is trusted
-      #
-      # @param user_id [String, Integer] User ID
-      # @return [Boolean]
-      def trusted_user?(user_id)
-        status = lookup_user(user_id)
-        status&.start_with?("trusted")
-      end
-
-      # Lookup session reputation
-      #
-      # @param session_id [String] Session ID
-      # @return [String, nil] Status string or nil
-      def lookup_session(session_id)
-        result = lookup(:session, session_id)
-        result&.dig(:status)
-      end
-
-      # Check if a session is trusted
-      #
-      # @param session_id [String] Session ID
-      # @return [Boolean]
-      def trusted_session?(session_id)
-        status = lookup_session(session_id)
-        status&.start_with?("trusted")
-      end
-
       private
 
       def valid_entity_type?(entity_type)

data/lib/reputable/tracker.rb

@@ -18,9 +18,6 @@ module Reputable
       # @param options [Hash] Additional options
       # @option options [String] :query Query string
       # @option options [String] :method HTTP method (GET, POST, etc.)
-      # @option options [String] :session_id Session identifier
-      # @option options [Boolean] :session_present Whether a session cookie exists
-      # @option options [String] :user_id Internal user ID (for logged-in users)
       # @option options [String] :fingerprint Browser fingerprint hash
       # @option options [String] :user_agent User-Agent header
       # @option options [String] :referer Referer header
@@ -41,11 +38,9 @@ module Reputable
       #     path: request.path,
       #     query: request.query_string,
       #     method: request.request_method,
-      #     session_id: session.id,
-      #     session_present: true,
       #     user_agent: request.user_agent,
       #     referer: request.referer,
-      #     tags: ["ctx:page:product", "trust:channel:organic"]
+      #     tags: ["view:page:product", "trust:channel:organic"]
       #   )
       def track_request(ip:, path:, **options)
         return false unless Reputable.enabled?
@@ -80,9 +75,6 @@ module Reputable
           path: path,
           query: options[:query],
           method: options[:method] || "GET",
-          session_id: options[:session_id],
-          session_present: options[:session_present],
-          user_id: options[:user_id],
           fingerprint: options[:fingerprint],
           user_agent: options[:user_agent],
           referer: options[:referer],

data/lib/reputable/version.rb

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

data/lib/reputable.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "reputable/version"
+require "json"
+require "base64"
 require_relative "reputable/configuration"
 require_relative "reputable/connection"
 require_relative "reputable/tracker"
@@ -23,14 +25,12 @@ end
 # @example Basic setup
 #   Reputable.configure do |config|
 #     config.redis_url = "rediss://user:pass@dragonfly.example.com:6379"
-#     config.tenant_id = "my-tenant"
 #   end
 #
 # @example Track a request
 #   Reputable.track_request(
 #     ip: "203.0.113.45",
-#     path: "/products/123",
-#     session_present: true
+#     path: "/products/123"
 #   )
 #
 # @example Apply reputation after payment
@@ -104,14 +104,6 @@ module Reputable
       Reputation.ignore_ip(ip, reason: reason, **metadata)
     end
 
-    def trust_user(user_id, reason: "verified_user", **metadata)
-      Reputation.trust_user(user_id, reason: reason, **metadata)
-    end
-
-    def trust_session(session_id, reason: "verified_session", **metadata)
-      Reputation.trust_session(session_id, reason: reason, **metadata)
-    end
-
     # Delegate lookup methods to Reputation module (O(1) Redis lookups)
     def lookup_reputation(entity_type, entity_id)
       Reputation.lookup(entity_type, entity_id)
@@ -133,20 +125,92 @@ module Reputable
       Reputation.challenged_ip?(ip)
     end
 
-    def lookup_user(user_id)
-      Reputation.lookup_user(user_id)
-    end
-
-    def trusted_user?(user_id)
-      Reputation.trusted_user?(user_id)
-    end
-
-    def lookup_session(session_id)
-      Reputation.lookup_session(session_id)
-    end
-
-    def trusted_session?(session_id)
-      Reputation.trusted_session?(session_id)
+    # Generate a signed verification URL
+    def verification_url(return_url:, failure_url: nil, session_id: nil)
+      keys = configuration.trusted_keys
+      if keys.nil? || keys.empty?
+        logger&.warn "Reputable: Missing trusted_keys, cannot generate verification URL"
+        return return_url 
+      end
+      
+      # Use the first key for signing new requests
+      secret = keys.first
+      
+      base_url = configuration.verification_base_url
+      
+      # JWT Header
+      header = { alg: "HS256", typ: "JWT" }
+      encoded_header = base64url_encode(JSON.generate(header))
+      
+      # JWT Payload
+      payload = {
+        returnUrl: return_url,
+        failureUrl: failure_url,
+        sessionId: session_id,
+        iat: Time.now.to_i
+      }
+      encoded_payload = base64url_encode(JSON.generate(payload))
+      
+      # Signature
+      data = "#{encoded_header}.#{encoded_payload}"
+      signature = OpenSSL::HMAC.digest("SHA256", secret, data)
+      encoded_signature = base64url_encode(signature)
+      
+      token = "#{data}.#{encoded_signature}"
+      
+      "#{base_url}?token=#{token}"
+    end
+
+    # Verify the signature of a redirect return
+    # @param params [Hash] Request query parameters
+    # @return [Boolean] true if valid logic and passed signature check
+    def verify_redirect_return(params)
+      status = params["reputable_status"]
+      session_id = params["reputable_session_id"]
+      signature = params["reputable_signature"]
+      outcome = params["reputable_outcome"]
+      ignore_analytics = params["reputable_ignore_analytics"]
+      country = params["reputable_country"] || ""
+      
+      return false unless status && session_id && signature
+      
+      keys = configuration.trusted_keys
+      if keys.nil? || keys.empty?
+        logger&.warn "Reputable: Missing trusted_keys, cannot verify redirect"
+        return false
+      end
+      
+      # Reconstruct data string: status:sessionId:outcome:ignoreAnalytics:country
+      # Note: optional params default to empty strings if missing in reconstruction logic on server
+      data_parts = [
+        status,
+        session_id,
+        outcome || "",
+        ignore_analytics.nil? ? "" : ignore_analytics,
+        country
+      ]
+      
+      data = data_parts.join(":")
+      
+      # Iterate through all trusted keys to find a match
+      keys.any? do |key|
+        expected_signature = OpenSSL::HMAC.hexdigest("SHA256", key, data)
+        secure_compare(expected_signature, signature)
+      end
+    end
+
+    private
+    
+    def base64url_encode(str)
+      Base64.urlsafe_encode64(str).gsub("=", "")
+    end
+
+    def secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+      l = a.unpack "C#{a.bytesize}"
+      res = 0
+      b.each_byte { |byte| res |= byte ^ l.shift }
+      res == 0
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: reputable
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Reputable
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-12-20 00:00:00.000000000 Z
+date: 2025-12-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -122,8 +122,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".DS_Store"
 - Gemfile
+- Gemfile.lock
 - README.md
+- Rakefile
 - lib/reputable.rb
 - lib/reputable/configuration.rb
 - lib/reputable/connection.rb