reputable 0.1.25 → 0.1.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71bd7ca4b8c5f9ed7587e464ae373eb944a54e51c5fb2ba119c32e8e6337336a
-  data.tar.gz: 2061b0c777149a2a689eed5dfa6c1ee429f4aa433d02fce31be31b200b46c93c
+  metadata.gz: 85f3feb44268a1779722dac5bd55976e534db3ea5d4ff86b541b96fb953c4c5d
+  data.tar.gz: a86937950a3032633c0bc81b4fce24ea833dc68c38f5eb7aecf071cecdbbc17f
 SHA512:
-  metadata.gz: 9faf4fe50a95dc50a5e13d33c215ea3894de64dace21176f5cbfd0f8794f6365ca53edb34b4fbabf0a7a8136bdea109b1d9519856c9197a45d2bfdcd43077310
-  data.tar.gz: bda70059416410192c65851f2ab96169958b87912c7e462fc350f866d59379d0e153419297c5c2b90aa26e9e65acab5c5f32ed293ce3bc30b878609b29823c90
+  metadata.gz: 851d6c143940682015369cb1592fad14742e271550dcc36bb2717f404c0c3c13883ed7abc7de6ffaee8b3baa34e15850353aa55085e5a5f79955a6f16ceb687a
+  data.tar.gz: b9cc8b8dacbbbc9731a806d15380e3455ae21ab78e0b0a09990a6db721cc26bbae51383afffb9a0de07fc7953a4098a4d06340d7bbc23ea2a1e84c7e8197c56f

data/Gemfile.lock

@@ -1,7 +1,8 @@
 PATH
   remote: .
   specs:
-    reputable (0.1.25)
+    reputable (0.1.26)
+      base64 (>= 0.2, < 0.4)
       connection_pool (~> 2.2)
       redis (>= 4.0, < 6.0)
 
@@ -9,25 +10,26 @@ GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
+    base64 (0.3.0)
     connection_pool (2.5.5)
     diff-lcs (1.6.2)
-    json (2.18.0)
+    json (2.19.8)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
-    parallel (1.27.0)
-    parser (3.3.10.0)
+    parallel (1.28.0)
+    parser (3.3.11.1)
       ast (~> 2.4.1)
       racc
-    prism (1.7.0)
+    prism (1.9.0)
     racc (1.8.1)
-    rack (2.2.21)
+    rack (2.2.23)
     rainbow (3.1.1)
-    rake (13.3.1)
+    rake (13.4.2)
     redis (5.4.1)
       redis-client (>= 0.22.0)
-    redis-client (0.26.2)
+    redis-client (0.29.0)
       connection_pool
-    regexp_parser (2.11.3)
+    regexp_parser (2.12.0)
     rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
@@ -37,24 +39,24 @@ GEM
     rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.7)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.6)
-    rubocop (1.82.0)
+    rspec-support (3.13.7)
+    rubocop (1.87.0)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
-      parallel (~> 1.10)
+      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)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.48.0)
+    rubocop-ast (1.49.1)
       parser (>= 3.3.7.2)
-      prism (~> 1.4)
+      prism (~> 1.7)
     ruby-progressbar (1.13.0)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
@@ -69,8 +71,8 @@ DEPENDENCIES
   rack (~> 2.0)
   rake (~> 13.0)
   reputable!
-  rspec (~> 3.0)
-  rubocop (~> 1.21)
+  rspec (~> 3.12, ~> 3.0)
+  rubocop (~> 1.21, ~> 1.0)
 
 BUNDLED WITH
-   2.5.9
+  4.0.14

data/README.md

@@ -245,6 +245,77 @@ REPUTABLE_SSL_VERIFY=false
 
 ---
 
+## Hosted Measurement
+
+Hosted measurement is the shared `cloud.reputable.click` path for per-request
+proxy, bot, timing, ASN, geo, and anomaly checks. It does not require Redis and
+does not replace the dedicated Reputable middleware path above.
+
+Configure the customer credentials issued from the Reputable `/measure` page:
+
+```ruby
+Reputable.configure do |config|
+  config.measurement_base_url = ENV["REPUTABLE_MEASURE_BASE_URL"] # e.g. https://cloud.reputable.click
+  config.measurement_customer_id = ENV["REPUTABLE_MEASURE_CUSTOMER_ID"]
+  config.measurement_capability = ENV["REPUTABLE_MEASURE_CAPABILITY"]
+  config.measurement_private_jwk = JSON.parse(ENV.fetch("REPUTABLE_MEASURE_PRIVATE_JWK"))
+end
+```
+
+Mint a short-lived token for the browser to send to the hosted collect endpoint:
+
+```ruby
+token = Reputable.measurement_token(
+  mode: "collect",
+  session_ref: session.id,
+  request_id: request.request_id,
+  origin: request.base_url,
+  request_context: {
+    scheme: request.scheme,
+    host: request.host,
+    method: request.request_method,
+    path: request.path,
+    query: request.query_string,
+    page_type: "product",
+    action_type: "view"
+  }
+)
+
+collect_url = Reputable.measurement_collect_url(token)
+```
+
+After the browser returns the signed `resultToken`, verify it server-side before
+allowing an expensive or abuse-sensitive action:
+
+```ruby
+result = Reputable.verify_measurement_result(result_token)
+
+if result && result["outcome"] != "deny"
+  # Continue with the protected action.
+else
+  # Review, challenge, or block according to your app policy.
+end
+```
+
+For offline verification without fetching JWKS from the measurement fleet, set:
+
+```ruby
+config.measurement_result_jwks = JSON.parse(ENV.fetch("REPUTABLE_MEASURE_RESULT_JWKS"))
+```
+
+Relevant environment variables:
+
+```bash
+REPUTABLE_MEASURE_BASE_URL=https://cloud.reputable.click
+REPUTABLE_MEASURE_CUSTOMER_ID=cus_...
+REPUTABLE_MEASURE_CAPABILITY=eyJ...
+REPUTABLE_MEASURE_PRIVATE_JWK='{"kty":"EC","crv":"P-256",...}'
+REPUTABLE_MEASURE_RESULT_JWKS='{"keys":[...]}'
+REPUTABLE_MEASURE_TOKEN_TTL=120
+```
+
+---
+
 ## Middleware Configuration
 
 ### Basic Usage
@@ -471,6 +542,43 @@ Reputable.track_request_async(
 )
 ```
 
+### Trusted Security Events
+
+For the full cross-service contract and Go API behavior, see [docs/SECURITY_EVENTS.md](../../docs/SECURITY_EVENTS.md).
+
+```ruby
+Reputable.track_security_event(
+  event_type: "login_failed",
+  ip: request.ip,
+  account_id: current_account.id,
+  user_id: current_user.id,
+  session_id: session.id.to_s,
+  request_id: request.request_id,
+  reason_code: "invalid_password",
+  context: {
+    country: "US",
+    proxy_class: "none",
+    ja4: request.headers["X-JA4"],
+    ua_family: "chrome"
+  },
+  resource: {
+    type: "account",
+    id: current_account.id,
+    action: "login"
+  },
+  metadata: { auth_method: "password" }
+)
+
+# Async (recommended)
+Reputable.track_security_event_async(
+  event_type: "permission_denied",
+  ip: request.ip,
+  account_id: current_account.id,
+  user_id: current_user.id,
+  reason_code: "missing_scope"
+)
+```
+
 ### Reputation Management
 
 ```ruby
@@ -645,14 +753,14 @@ 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 params[:reputable_s] || 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.
+
+    decoded = Reputable.decode_reputable_response(params)
+    status = decoded&.dig("status") || params[:reputable_status]
+    outcome = decoded&.dig("outcome") || params[:reputable_outcome]
+    country = decoded&.dig("country") || params[:reputable_country]
     
     if status == 'pass'
       # Grant access
@@ -665,14 +773,21 @@ 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_challenge_passed`: 'true' when an interactive challenge was completed
-- `reputable_signature`: HMAC-SHA256 signature of the above
+The current Go API returns compact signed parameters:
+
+- `reputable_r`: Base64url-encoded response payload
+- `reputable_s`: HMAC-SHA256 signature of the decoded payload
+
+Decode `reputable_r` with `Reputable.decode_reputable_response(params)` to read:
+
+- `status`: `pass` or `fail`
+- `session_id`: The session ID you provided
+- `outcome`: The specific reputation outcome (e.g., `trusted_verified`)
+- `ignore_analytics`: `true`/`false` flag
+- `country`: ISO country code
+- `challenge_passed`: `true` when an interactive challenge was completed
+
+The Ruby client still accepts the legacy expanded parameters (`reputable_status`, `reputable_session_id`, `reputable_outcome`, `reputable_ignore_analytics`, `reputable_country`, `reputable_challenge_passed`, `reputable_signature`) for backward compatibility.
 
 ---
 

data/lib/reputable/configuration.rb

@@ -2,6 +2,7 @@
 
 require "openssl"
 require "ipaddr"
+require "json"
 
 module Reputable
   # Configuration class for Reputable client
@@ -15,6 +16,11 @@ module Reputable
                   :connect_timeout, :read_timeout, :write_timeout,
                   :ssl_params, :trusted_proxies, :ip_header_priority,
                   :on_error, :trusted_keys, :base_url,
+                  :measurement_base_url, :measurement_customer_id,
+                  :measurement_result_jwks, :measurement_audience,
+                  :signals_secret_key, :signals_publishable_key,
+                  :measurement_capability, :measurement_private_jwk,
+                  :measurement_token_ttl,
                   :site_name, :support_email, :support_url,
                   :verbose
 
@@ -80,6 +86,17 @@ module Reputable
         @trusted_keys = [ENV["REPUTABLE_SECRET_KEY"]]
       end
       @base_url = ENV.fetch("REPUTABLE_BASE_URL", "https://api.reputable.click")
+      @measurement_base_url = ENV["REPUTABLE_SIGNALS_BASE_URL"] || ENV["REPUTABLE_MEASURE_BASE_URL"]
+      @measurement_customer_id = ENV["REPUTABLE_SIGNALS_CUSTOMER_ID"] || ENV["REPUTABLE_MEASURE_CUSTOMER_ID"]
+      @measurement_result_jwks = parse_json_env("REPUTABLE_SIGNALS_JWKS") || parse_json_env("REPUTABLE_MEASURE_RESULT_JWKS")
+      @measurement_audience = ENV.fetch("REPUTABLE_MEASURE_AUDIENCE", "reputable-measure")
+      @signals_secret_key = ENV["REPUTABLE_SIGNALS_SECRET_KEY"]
+      @signals_publishable_key = ENV["REPUTABLE_SIGNALS_PUBLISHABLE_KEY"]
+      # Legacy capability-era settings; kept as readable attributes so old
+      # initializers do not crash, but no longer used.
+      @measurement_capability = ENV["REPUTABLE_MEASURE_CAPABILITY"]
+      @measurement_private_jwk = parse_json_env("REPUTABLE_MEASURE_PRIVATE_JWK")
+      @measurement_token_ttl = Integer(ENV.fetch("REPUTABLE_MEASURE_TOKEN_TTL", "120"))
       @site_name = ENV["REPUTABLE_SITE_NAME"]
       @support_email = ENV["REPUTABLE_SUPPORT_EMAIL"]
       @support_url = ENV["REPUTABLE_SUPPORT_URL"]
@@ -124,6 +141,15 @@ module Reputable
       @default_ttls[status_sym] || DEFAULT_TTLS[:untrusted_challenge]
     end
 
+    def parse_json_env(name)
+      raw = ENV[name]
+      return nil if raw.nil? || raw.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      nil
+    end
+
     # Check if Redis URL uses TLS (rediss:// scheme)
     def tls?
       redis_url&.start_with?("rediss://")

data/lib/reputable/measurement.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "net/http"
+require "openssl"
+require "securerandom"
+require "time"
+require "uri"
+
+module Reputable
+  # Helpers for the hosted Bot Signals API.
+  #
+  # This path is independent from the Redis-backed reputation middleware. It
+  # verifies signed tickets offline against the published JWKS. The old
+  # customer-minted measurement-token flow is gone: servers call the check API
+  # with a plain secret key (see Reputable::Signals) and browsers use a
+  # publishable key.
+  module Measurement
+    DEFAULT_AUDIENCE = "reputable-measure"
+
+    MINTING_REMOVED = "Reputable no longer uses customer-minted measurement tokens. " \
+                      "Use your secret key with Reputable::Signals.check (server) or your " \
+                      "publishable key in the browser snippet/redirect URL instead."
+
+    module_function
+
+    # @deprecated The two-key model replaced customer-minted JWTs.
+    def measurement_token(**)
+      raise NotImplementedError, MINTING_REMOVED
+    end
+
+    # @deprecated See {Reputable::Signals.redirect_url}.
+    def collect_url(_token = nil)
+      raise NotImplementedError, MINTING_REMOVED
+    end
+
+    # @deprecated See {Reputable::Signals.redirect_url}.
+    def redirect_url(_token = nil)
+      raise NotImplementedError, MINTING_REMOVED
+    end
+
+    def verify_result_token(token, jwks: nil, expected_customer_id: nil, audience: nil)
+      return nil if blank?(token)
+
+      jwks ||= Reputable.configuration.measurement_result_jwks || fetch_measurement_jwks
+      keys = Array(jwks.is_a?(Hash) ? jwks["keys"] || jwks[:keys] : jwks)
+      return nil if keys.empty?
+
+      header, payload, signed_data, signature = decode_jwt(token)
+      return nil unless header["alg"] == "ES256"
+
+      key = select_key(keys, header["kid"])
+      return nil unless key && verify_es256_signature(key, signed_data, signature)
+
+      now = Time.now.to_i
+      return nil if payload["exp"] && now >= payload["exp"].to_i
+      return nil if payload["nbf"] && now < payload["nbf"].to_i
+
+      expected_customer_id ||= Reputable.configuration.measurement_customer_id
+      audience ||= expected_customer_id
+      return nil if present?(expected_customer_id) && payload["customerId"] != expected_customer_id
+      return nil if present?(audience) && !audience_matches?(payload["aud"], audience)
+
+      payload
+    rescue StandardError => e
+      Reputable.logger&.warn "Reputable: Failed to verify measurement result: #{e.message}"
+      nil
+    end
+
+    def verify_result(token, **kwargs)
+      claims = verify_result_token(token, **kwargs)
+      claims && (claims["report"] || claims["result"])
+    end
+
+    def measurement_base_url
+      (Reputable.configuration.measurement_base_url || Reputable.configuration.base_url).to_s.chomp("/")
+    end
+
+    def fetch_measurement_jwks
+      fetch_jwks_path("/v1/signals/jwks") || fetch_jwks_path("/v1/verify/jwks")
+    end
+
+    def fetch_jwks_path(path)
+      uri = URI("#{measurement_base_url}#{path}")
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                                     open_timeout: Reputable.configuration.connect_timeout,
+                                                     read_timeout: Reputable.configuration.read_timeout) do |http|
+        http.get(uri.request_uri)
+      end
+      return nil unless response.is_a?(Net::HTTPSuccess)
+
+      JSON.parse(response.body)
+    rescue StandardError => e
+      Reputable.logger&.warn "Reputable: Failed to fetch JWKS from #{path}: #{e.message}"
+      nil
+    end
+
+    def normalize_request_context(value)
+      raw = stringify_keys(value || {})
+      {
+        scheme: raw["scheme"],
+        host: raw["host"],
+        method: raw["method"]&.upcase,
+        path: raw["path"],
+        query: raw["query"],
+        url: raw["url"],
+        referrer: raw["referrer"] || raw["referer"],
+        pageTitle: raw["pageTitle"] || raw["page_title"],
+        pageType: raw["pageType"] || raw["page_type"],
+        actionType: raw["actionType"] || raw["action_type"]
+      }.compact
+    end
+
+    def sign_es256_jwt(payload, private_jwk)
+      jwk = stringify_keys(private_jwk)
+      header = { alg: "ES256", typ: "JWT" }
+      header[:kid] = jwk["kid"] if present?(jwk["kid"])
+
+      signed_data = "#{base64url_encode(JSON.generate(header))}.#{base64url_encode(JSON.generate(payload))}"
+      der_signature = ec_private_key_from_jwk(jwk).dsa_sign_asn1(OpenSSL::Digest::SHA256.digest(signed_data))
+      "#{signed_data}.#{base64url_encode(der_to_jose_signature(der_signature))}"
+    end
+
+    def decode_jwt(token)
+      parts = token.to_s.split(".")
+      raise ArgumentError, "invalid JWT" unless parts.length == 3
+
+      header = JSON.parse(base64url_decode(parts[0]))
+      payload = JSON.parse(base64url_decode(parts[1]))
+      [header, payload, "#{parts[0]}.#{parts[1]}", base64url_decode(parts[2])]
+    end
+
+    def verify_es256_signature(jwk, signed_data, jose_signature)
+      return false unless jose_signature.bytesize == 64
+
+      digest = OpenSSL::Digest::SHA256.digest(signed_data)
+      ec_public_key_from_jwk(stringify_keys(jwk)).dsa_verify_asn1(digest, jose_to_der_signature(jose_signature))
+    rescue StandardError
+      false
+    end
+
+    # Keys are built from DER rather than assigned via key.private_key= /
+    # key.public_key=, which raise "pkeys are immutable" on OpenSSL 3.
+    def ec_private_key_from_jwk(jwk)
+      d = base64url_decode(jwk.fetch("d"))
+      asn1 = OpenSSL::ASN1::Sequence([
+        OpenSSL::ASN1::Integer(1),
+        OpenSSL::ASN1::OctetString(d.rjust(32, "\x00")),
+        OpenSSL::ASN1::ASN1Data.new([OpenSSL::ASN1::ObjectId("prime256v1")], 0, :CONTEXT_SPECIFIC),
+        OpenSSL::ASN1::ASN1Data.new(
+          [OpenSSL::ASN1::BitString(public_point_from_jwk(jwk).to_octet_string(:uncompressed))],
+          1, :CONTEXT_SPECIFIC
+        )
+      ])
+      OpenSSL::PKey::EC.new(asn1.to_der)
+    end
+
+    def ec_public_key_from_jwk(jwk)
+      asn1 = OpenSSL::ASN1::Sequence([
+        OpenSSL::ASN1::Sequence([
+          OpenSSL::ASN1::ObjectId("id-ecPublicKey"),
+          OpenSSL::ASN1::ObjectId("prime256v1")
+        ]),
+        OpenSSL::ASN1::BitString(public_point_from_jwk(jwk).to_octet_string(:uncompressed))
+      ])
+      OpenSSL::PKey::EC.new(asn1.to_der)
+    end
+
+    def public_point_from_jwk(jwk)
+      group = OpenSSL::PKey::EC::Group.new("prime256v1")
+      x = base64url_decode(jwk.fetch("x"))
+      y = base64url_decode(jwk.fetch("y"))
+      OpenSSL::PKey::EC::Point.new(group, OpenSSL::BN.new("\x04#{x}#{y}", 2))
+    end
+
+    def der_to_jose_signature(der)
+      sequence = OpenSSL::ASN1.decode(der)
+      r = integer_to_fixed_bytes(sequence.value[0].value.to_i, 32)
+      s = integer_to_fixed_bytes(sequence.value[1].value.to_i, 32)
+      "#{r}#{s}"
+    end
+
+    def jose_to_der_signature(signature)
+      r = OpenSSL::BN.new(signature[0, 32], 2)
+      s = OpenSSL::BN.new(signature[32, 32], 2)
+      OpenSSL::ASN1::Sequence([
+        OpenSSL::ASN1::Integer(r),
+        OpenSSL::ASN1::Integer(s)
+      ]).to_der
+    end
+
+    def integer_to_fixed_bytes(value, width)
+      hex = value.to_s(16)
+      hex = "0#{hex}" if hex.length.odd?
+      bytes = [hex].pack("H*")
+      bytes.rjust(width, "\x00")[-width, width]
+    end
+
+    def select_key(keys, kid)
+      keys = keys.map { |key| stringify_keys(key) }
+      return keys.first if blank?(kid) && keys.length == 1
+
+      keys.find { |key| key["kid"] == kid }
+    end
+
+    def audience_matches?(actual, expected)
+      Array(actual).map(&:to_s).include?(expected.to_s)
+    end
+
+    def stringify_keys(value)
+      return value unless value.is_a?(Hash)
+
+      value.each_with_object({}) { |(key, val), out| out[key.to_s] = val }
+    end
+
+    def base64url_encode(value)
+      Base64.urlsafe_encode64(value).delete("=")
+    end
+
+    def base64url_decode(value)
+      padded = value.to_s + "=" * ((4 - value.to_s.length % 4) % 4)
+      Base64.urlsafe_decode64(padded)
+    end
+
+    def escape(value)
+      URI.encode_www_form_component(value.to_s)
+    end
+
+    def present?(value)
+      !blank?(value)
+    end
+
+    def blank?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+  end
+end

data/lib/reputable/middleware.rb

@@ -456,6 +456,9 @@ module Reputable
         path: request.path,
         query: request.query_string.empty? ? nil : request.query_string,
         method: request.request_method,
+        account_id: tracking_account_id(env),
+        session_id: tracking_session_id(env),
+        user_id: tracking_user_id(env),
         user_agent: env["HTTP_USER_AGENT"],
         referer: env["HTTP_REFERER"],
         tags: build_tags(env),
@@ -466,6 +469,34 @@ module Reputable
       nil
     end
 
+    def tracking_session_id(env)
+      resolve_session_id(env)
+    rescue StandardError
+      nil
+    end
+
+    def tracking_user_id(env)
+      return env["reputable.user_id"] if env["reputable.user_id"]
+
+      session = env["rack.session"]
+      return nil unless session
+
+      session[:user_id] || session["user_id"]
+    rescue StandardError
+      nil
+    end
+
+    def tracking_account_id(env)
+      return env["reputable.account_id"] if env["reputable.account_id"]
+
+      session = env["rack.session"]
+      return nil unless session
+
+      session[:account_id] || session["account_id"] || session[:tenant_id] || session["tenant_id"]
+    rescue StandardError
+      nil
+    end
+
     def extract_ip(env)
       config = Reputable.configuration
 

data/lib/reputable/rails.rb

@@ -25,6 +25,41 @@ module Reputable
         )
       end
 
+      # Track a trusted backend security event for user/account profiling.
+      def track_reputable_security_event(
+        event_type:,
+        outcome: nil,
+        reason_code: nil,
+        account_id: nil,
+        user_id: nil,
+        context: {},
+        resource: nil,
+        metadata: {},
+        **options
+      )
+        base_context = {
+          ip: request.remote_ip
+        }.merge(context || {})
+
+        Reputable::Tracker.track_security_event(
+          event_type: event_type,
+          ip: request.remote_ip,
+          path: request.path,
+          outcome: outcome,
+          reason_code: reason_code,
+          account_id: account_id,
+          user_id: user_id,
+          session_id: options[:session_id] || session.id,
+          request_id: options[:request_id] || request.request_id,
+          user_agent: request.user_agent,
+          referer: request.referer,
+          context: base_context,
+          resource: resource,
+          metadata: metadata,
+          **options
+        )
+      end
+
       # Trust the current user's IP (behavioral by default, verified optional)
       def trust_current_ip(reason:, status: :trusted_behavior, ttl: nil, **metadata)
         Reputable::Reputation.trust_ip(

data/lib/reputable/signals.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "json"
+require "net/http"
+require "uri"
+
+module Reputable
+  # Bot Signals server API: ask the hosted fleet for a signal report on an end
+  # user's request using your secret key (sk_...). No JWT minting — a plain
+  # bearer.
+  #
+  # @example Check a request before an expensive action
+  #   check = Reputable::Signals.check(ip: request.remote_ip, user_agent: request.user_agent)
+  #   report = check && check["report"]
+  #   flag_traffic if report && report["proxyScore"].to_i >= 70
+  module Signals
+    module_function
+
+    # POST /v1/signals/check with the configured secret key. Pass the END
+    # USER's ip/user_agent — without them the fleet would score your server's
+    # own connection. Returns the parsed response hash ({"ticket", "report"})
+    # or nil on failure.
+    def check(ip: nil, user_agent: nil, session_ref: nil, request_id: nil, request_context: nil,
+              detail: false, secret_key: nil)
+      secret_key ||= Reputable.configuration.signals_secret_key
+      return nil if secret_key.nil? || secret_key.empty?
+
+      uri = URI("#{Measurement.measurement_base_url}/v1/signals/check")
+      payload = {
+        ip: ip,
+        userAgent: user_agent,
+        sessionRef: session_ref,
+        requestId: request_id,
+        detail: detail || nil
+      }
+      payload[:request] = Measurement.normalize_request_context(request_context) if request_context
+
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                                     open_timeout: Reputable.configuration.connect_timeout,
+                                                     read_timeout: Reputable.configuration.read_timeout) do |http|
+        request = Net::HTTP::Post.new(uri.request_uri, "Content-Type" => "application/json",
+                                                       "Authorization" => "Bearer #{secret_key}")
+        request.body = JSON.generate(payload.compact)
+        http.request(request)
+      end
+      return nil unless response.is_a?(Net::HTTPSuccess)
+
+      data = JSON.parse(response.body)
+      data["report"] ||= data["result"]
+      data["ticket"] ||= data["proof"]
+      data
+    rescue StandardError => e
+      Reputable.logger&.warn "Reputable: signals check failed: #{e.message}"
+      nil
+    end
+
+    # Build a redirect-flow URL: send a visitor through the fleet and back to
+    # +return_url+ (which must be registered on the publishable key) with a
+    # signed ticket attached as ?reputable_ticket=...
+    def redirect_url(return_url:, key: nil, request_id: nil, session_ref: nil)
+      key ||= Reputable.configuration.signals_publishable_key
+      raise ArgumentError, "publishable key is required" if key.nil? || key.empty?
+      raise ArgumentError, "return_url is required" if return_url.nil? || return_url.empty?
+
+      params = { key: key, return: return_url, request_id: request_id, session: session_ref }.compact
+      query = params.map { |k, v| "#{k}=#{CGI.escape(v.to_s)}" }.join("&")
+      "#{Measurement.measurement_base_url}/v1/signals/redirect?#{query}"
+    end
+
+    # Build a hosted challenge-page URL. The return URL must be registered on
+    # the publishable key. Clean traffic redirects back immediately; suspect
+    # traffic receives the key's configured CAPTCHA.
+    def challenge_page_url(return_url:, key: nil, request_id: nil, session_ref: nil)
+      key ||= Reputable.configuration.signals_publishable_key
+      raise ArgumentError, "publishable key is required" if key.nil? || key.empty?
+      raise ArgumentError, "return_url is required" if return_url.nil? || return_url.empty?
+
+      params = { key: key, return: return_url, request_id: request_id, session: session_ref }.compact
+      query = params.map { |k, v| "#{k}=#{CGI.escape(v.to_s)}" }.join("&")
+      "#{Measurement.measurement_base_url}/v1/signals/challenge-page?#{query}"
+    end
+  end
+end

data/lib/reputable/tracker.rb

@@ -68,6 +68,81 @@ module Reputable
         true
       end
 
+      # Track a trusted backend security event (risk_event_v1 envelope).
+      #
+      # This is transported through the request buffer with metadata.risk_event_v1
+      # so existing classification/rule pipelines can consume resulting tags.
+      def track_security_event(
+        event_type:,
+        ip: nil,
+        account_id: nil,
+        user_id: nil,
+        session_id: nil,
+        request_id: nil,
+        outcome: nil,
+        reason_code: nil,
+        context: {},
+        resource: nil,
+        metadata: {},
+        occurred_at_ms: nil,
+        path: "/_trusted/security_event",
+        **options
+      )
+        return false unless Reputable.enabled?
+        normalized_event_type = normalize_token(event_type)
+        return false if normalized_event_type.nil? || normalized_event_type.empty?
+
+        event_context = normalize_risk_context(context)
+        effective_ip = ip || event_context[:ip]
+        return false if effective_ip.nil? || effective_ip.to_s.strip.empty?
+
+        risk_event = build_risk_event_v1(
+          event_type: normalized_event_type,
+          occurred_at_ms: occurred_at_ms,
+          account_id: account_id || options[:account_id],
+          user_id: user_id || options[:user_id],
+          session_id: session_id || options[:session_id],
+          request_id: request_id || options[:request_id],
+          outcome: outcome,
+          reason_code: reason_code,
+          context: event_context,
+          resource: resource,
+          metadata: metadata
+        )
+
+        entry_metadata = merge_metadata(options[:metadata], metadata)
+        entry_metadata[:risk_event_v1] = risk_event
+
+        tags = Array(options[:tags]) + security_tags_for_event(risk_event)
+
+        entry = build_request_entry(effective_ip, path, options.merge(
+          method: options[:method] || "POST",
+          account_id: account_id || options[:account_id],
+          user_id: user_id || options[:user_id],
+          session_id: session_id || options[:session_id],
+          request_id: request_id || options[:request_id],
+          tags: tags,
+          metadata: entry_metadata
+        ))
+
+        push_to_buffer(:request, entry)
+      rescue StandardError => e
+        Reputable.logger&.debug("Reputable track_security_event error: #{e.class} - #{e.message}")
+        false
+      end
+
+      # Fire-and-forget variant of track_security_event.
+      def track_security_event_async(**kwargs)
+        return true unless Reputable.enabled?
+
+        Thread.new do
+          track_security_event(**kwargs)
+        rescue StandardError
+          # Silently ignore all errors in async thread
+        end
+        true
+      end
+
       private
 
       def build_request_entry(ip, path, options)
@@ -77,16 +152,114 @@ module Reputable
           path: path,
           query: options[:query],
           method: options[:method] || "GET",
+          account_id: options[:account_id],
+          session_id: options[:session_id],
+          user_id: options[:user_id],
           fingerprint: options[:fingerprint],
           user_agent: options[:user_agent],
           referer: options[:referer],
           country: options[:country],
-          tags: options[:tags] || [],
+          tags: Array(options[:tags]),
           metadata: options[:metadata],
           request_id: options[:request_id]
         }.compact
       end
 
+      def build_risk_event_v1(
+        event_type:,
+        occurred_at_ms: nil,
+        account_id: nil,
+        user_id: nil,
+        session_id: nil,
+        request_id: nil,
+        outcome: nil,
+        reason_code: nil,
+        context: {},
+        resource: nil,
+        metadata: {}
+      )
+        {
+          event_type: normalize_token(event_type),
+          occurred_at_ms: occurred_at_ms || (Time.now.to_f * 1000).to_i,
+          account_id: account_id,
+          user_id: user_id,
+          session_id: session_id,
+          request_id: request_id,
+          outcome: normalize_token(outcome),
+          reason_code: normalize_token(reason_code),
+          context: context,
+          resource: normalize_resource(resource),
+          metadata: metadata
+        }.compact
+      end
+
+      def normalize_risk_context(context)
+        hash = context.respond_to?(:to_h) ? context.to_h : {}
+        {
+          ip: hash[:ip] || hash["ip"],
+          country: normalize_token(hash[:country] || hash["country"]),
+          asn: (hash[:asn] || hash["asn"])&.to_s,
+          proxy_class: normalize_token(hash[:proxy_class] || hash["proxy_class"]),
+          ja4: (hash[:ja4] || hash["ja4"])&.to_s,
+          ua_family: normalize_token(hash[:ua_family] || hash["ua_family"])
+        }.compact
+      end
+
+      def normalize_resource(resource)
+        return nil if resource.nil?
+
+        hash = resource.respond_to?(:to_h) ? resource.to_h : {}
+        {
+          type: normalize_token(hash[:type] || hash["type"]),
+          id: (hash[:id] || hash["id"])&.to_s,
+          action: normalize_token(hash[:action] || hash["action"])
+        }.compact
+      end
+
+      def security_tags_for_event(risk_event)
+        event_type = risk_event[:event_type]
+        outcome = risk_event[:outcome]
+        tags = ["security:event", "security:event:#{event_type}"]
+        case event_type
+        when "login_success"
+          tags << "trust:auth:login_success"
+        when "login_failed"
+          tags << "risk:suspicious:auth:login_failed"
+        when "permission_denied"
+          tags << "risk:suspicious:authz:permission_denied"
+        when "mfa_failed"
+          tags << "risk:suspicious:auth:mfa_failed"
+        when "account_locked"
+          tags << "risk:malicious:auth:account_locked"
+        when "password_reset"
+          tags << "trust:auth:password_reset"
+        when "account_unlock", "account_unlocked"
+          tags << "trust:auth:account_unlocked"
+        when "mfa_result"
+          if %w[fail failed].include?(outcome)
+            tags << "risk:suspicious:auth:mfa_failed"
+          elsif %w[success pass].include?(outcome)
+            tags << "trust:auth:mfa_success"
+          end
+        end
+        tags << "security:outcome:#{outcome}" unless outcome.nil? || outcome.empty?
+        tags.compact.uniq
+      end
+
+      def merge_metadata(*candidates)
+        merged = {}
+        candidates.compact.each do |item|
+          hash = item.respond_to?(:to_h) ? item.to_h : {}
+          hash.each { |k, v| merged[k.to_sym] = v }
+        end
+        merged
+      end
+
+      def normalize_token(value)
+        return nil if value.nil?
+        value.to_s.strip.downcase.gsub(/[^a-z0-9_-]+/, "_").gsub(/\A_+|_+\z/, "")
+      end
+
       def push_to_buffer(type, entry)
         key = case type
               when :request then Reputable.configuration.request_buffer_key

data/lib/reputable/verify.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Reputable
+  # Bot Signals — verify the signed ticket the widget (or the check endpoint)
+  # hands to your form. A ticket is a short-lived signed JWT carrying the
+  # visitor's signal report (network evidence, score, and whether a CAPTCHA was
+  # solved). Verify it offline against the published JWKS (no network call),
+  # with the hosted introspection endpoint as a fallback for environments that
+  # cannot fetch/cache the JWKS.
+  #
+  # What you do with the report is up to you: the "outcome" field is an
+  # advisory assessment derived from YOUR key's thresholds.
+  #
+  # @example Require a ticket on login
+  #   report = Reputable.verify_ticket(params["reputable-ticket"], customer_id: "cus_123")
+  #   if report && report["outcome"] == "allow"
+  #     # proceed; report["challengePassed"] tells you if a CAPTCHA was solved
+  #   else
+  #     # reject / re-challenge — your call
+  #   end
+  module Verify
+    module_function
+
+    # Verify a ticket and return its signal report hash (keys include
+    # "outcome", "challengePassed", "proxyScore", "rating", "signals", ...),
+    # or nil if invalid.
+    #
+    # Verification is offline-first (JWKS); if that yields nothing it falls back
+    # to the hosted introspection endpoint. When +session_ref+ is given it must
+    # match the ticket's subject.
+    def verify_ticket(ticket, **options)
+      claims = verify_ticket_claims(ticket, **options)
+      claims && (claims["report"] || claims["result"] || claims)
+    rescue StandardError => e
+      Reputable.logger&.warn "Reputable: verify_ticket failed: #{e.message}"
+      nil
+    end
+
+    # Verify a ticket and return the complete signed claims. Set
+    # +network_fallback: false+ in latency-sensitive request paths to prohibit
+    # both JWKS fetching and hosted introspection.
+    def verify_ticket_claims(ticket, customer_id: nil, session_ref: nil, jwks: nil,
+                             network_fallback: true, expected_key_id: nil,
+                             expected_mode: nil, expected_return_origin: nil)
+      return nil if blank?(ticket)
+
+      offline_jwks = jwks || Reputable.configuration.measurement_result_jwks
+      return nil if !network_fallback && offline_jwks.nil?
+
+      claims = Measurement.verify_result_token(
+        ticket,
+        jwks: offline_jwks,
+        expected_customer_id: customer_id
+      )
+      claims ||= introspect(ticket, customer_id: customer_id, session_ref: session_ref) if network_fallback
+      return nil unless claims
+
+      return nil unless claim_matches?(claims, "sessionRef", session_ref, alternate: "sub")
+      return nil unless claim_matches?(claims, "keyId", expected_key_id)
+      return nil unless claim_matches?(claims, "mode", expected_mode)
+      return nil unless return_origin_matches?(claims["returnOrigin"], expected_return_origin)
+
+      claims
+    rescue StandardError => e
+      Reputable.logger&.warn "Reputable: verify_ticket_claims failed: #{e.message}"
+      nil
+    end
+
+    # Legacy alias from the proof era.
+    def verify_proof(proof, **kwargs)
+      verify_ticket(proof, **kwargs)
+    end
+
+    # Convenience predicate: did this ticket clear a CAPTCHA challenge?
+    def challenge_passed?(ticket, **kwargs)
+      report = verify_ticket(ticket, **kwargs)
+      return false unless report
+
+      !!(report["challengePassed"] || report[:challengePassed])
+    end
+
+    # Introspection fallback: POST the ticket to the hosted service, which
+    # verifies it server-side and returns the report. Always treat a non-valid
+    # response as a rejection.
+    def introspect(ticket, customer_id: nil, session_ref: nil)
+      base = Measurement.measurement_base_url
+      uri = URI("#{base}/v1/signals/introspect")
+      payload = { ticket: ticket, customerId: customer_id, sessionRef: session_ref }.compact
+
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                                     open_timeout: Reputable.configuration.connect_timeout,
+                                                     read_timeout: Reputable.configuration.read_timeout) do |http|
+        request = Net::HTTP::Post.new(uri.request_uri, "Content-Type" => "application/json")
+        request.body = JSON.generate(payload)
+        http.request(request)
+      end
+      return nil unless response.is_a?(Net::HTTPSuccess)
+
+      data = JSON.parse(response.body)
+      return nil unless data["valid"]
+
+      { "report" => data["report"] || data["result"], "sessionRef" => data["sessionRef"], "customerId" => data["customerId"] }
+    rescue StandardError => e
+      Reputable.logger&.warn "Reputable: ticket introspection failed: #{e.message}"
+      nil
+    end
+
+    def present?(value)
+      !blank?(value)
+    end
+
+    def blank?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+
+    def claim_matches?(claims, key, expected, alternate: nil)
+      return true unless present?(expected)
+
+      values = [claims[key], alternate && claims[alternate]].compact
+      values.any? && values.all? { |value| value == expected }
+    end
+
+    def return_origin_matches?(actual, expected)
+      return true unless present?(expected)
+
+      normalized_actual = normalize_origin(actual)
+      normalized_expected = normalize_origin(expected)
+      normalized_actual && normalized_expected && normalized_actual == normalized_expected
+    end
+
+    def normalize_origin(value)
+      uri = URI(value.to_s)
+      return nil unless %w[http https].include?(uri.scheme) && present?(uri.host)
+
+      default_port = (uri.scheme == "https" ? 443 : 80)
+      port = uri.port == default_port ? "" : ":#{uri.port}"
+      "#{uri.scheme}://#{uri.host.downcase}#{port}"
+    rescue URI::InvalidURIError
+      nil
+    end
+  end
+end

data/lib/reputable/version.rb

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

data/lib/reputable.rb

@@ -7,6 +7,9 @@ require_relative "reputable/configuration"
 require_relative "reputable/connection"
 require_relative "reputable/tracker"
 require_relative "reputable/reputation"
+require_relative "reputable/measurement"
+require_relative "reputable/verify"
+require_relative "reputable/signals"
 require_relative "reputable/blocked_page"
 require_relative "reputable/middleware"
 
@@ -112,6 +115,14 @@ module Reputable
       Tracker.track_request_async(ip: ip, path: path, **options)
     end
 
+    def track_security_event(**kwargs)
+      Tracker.track_security_event(**kwargs)
+    end
+
+    def track_security_event_async(**kwargs)
+      Tracker.track_security_event_async(**kwargs)
+    end
+
     # Delegate reputation methods to Reputation module
     def apply_reputation(entity_type:, entity_id:, status:, **options)
       Reputation.apply(entity_type: entity_type, entity_id: entity_id, status: status, **options)
@@ -187,6 +198,64 @@ module Reputable
       Reputation.ignore_asn(asn, reason: reason, ttl: ttl, **metadata)
     end
 
+    def measurement_token(**kwargs)
+      Measurement.measurement_token(**kwargs)
+    end
+
+    def measurement_collect_url(token)
+      Measurement.collect_url(token)
+    end
+
+    def measurement_redirect_url(token)
+      Measurement.redirect_url(token)
+    end
+
+    def verify_measurement_result_token(token, **kwargs)
+      Measurement.verify_result_token(token, **kwargs)
+    end
+
+    def verify_measurement_result(token, **kwargs)
+      Measurement.verify_result(token, **kwargs)
+    end
+
+    # Bot Signals: verify the signed ticket submitted by the widget. Returns
+    # the signal report hash (incl. "outcome" and "challengePassed") or nil.
+    def verify_ticket(ticket, **kwargs)
+      Verify.verify_ticket(ticket, **kwargs)
+    end
+
+    # Bot Signals: verify and return all signed ticket claims. This is useful
+    # when an application must bind a route pass to key, mode, session, or
+    # return origin rather than reading only the report.
+    def verify_ticket_claims(ticket, **kwargs)
+      Verify.verify_ticket_claims(ticket, **kwargs)
+    end
+
+    # Legacy alias from the proof era.
+    def verify_proof(proof, **kwargs)
+      Verify.verify_ticket(proof, **kwargs)
+    end
+
+    # Did the ticket clear a CAPTCHA challenge? Convenience predicate.
+    def ticket_challenge_passed?(ticket, **kwargs)
+      Verify.challenge_passed?(ticket, **kwargs)
+    end
+
+    # Legacy alias from the proof era.
+    def proof_challenge_passed?(proof, **kwargs)
+      Verify.challenge_passed?(proof, **kwargs)
+    end
+
+    # Bot Signals server API: signal report for an end user's request.
+    def signals_check(**kwargs)
+      Signals.check(**kwargs)
+    end
+
+    # Bot Signals redirect-flow URL (publishable key + registered return URL).
+    def signals_redirect_url(**kwargs)
+      Signals.redirect_url(**kwargs)
+    end
+
     # Generate a signed verification URL
     # @param return_url [String] URL to redirect to after successful verification
     # @param failure_url [String, nil] URL to redirect to on failure (optional)

data/reputable.gemspec

@@ -29,6 +29,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "redis", ">= 4.0", "< 6.0"
   spec.add_dependency "connection_pool", "~> 2.2"
+  spec.add_dependency "base64", ">= 0.2", "< 0.4"
 
   spec.add_development_dependency "bundler", "~> 2.0"
   spec.add_development_dependency "rake", "~> 13.0"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: reputable
 version: !ruby/object:Gem::Version
-  version: 0.1.25
+  version: 0.1.26
 platform: ruby
 authors:
 - Reputable
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-11 00:00:00.000000000 Z
+date: 2026-07-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -44,6 +44,26 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.4'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -132,10 +152,13 @@ files:
 - lib/reputable/blocked_page.rb
 - lib/reputable/configuration.rb
 - lib/reputable/connection.rb
+- lib/reputable/measurement.rb
 - lib/reputable/middleware.rb
 - lib/reputable/rails.rb
 - lib/reputable/reputation.rb
+- lib/reputable/signals.rb
 - lib/reputable/tracker.rb
+- lib/reputable/verify.rb
 - lib/reputable/version.rb
 - reputable.gemspec
 homepage: https://github.com/reputable-click/reputable-rb