preverus 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 25c4aebb9cfa7bd4d2c05599cdd9feca312e5920ca06e18b2baad0f7382355ce
+  data.tar.gz: 3620728bc7d32c3056dcb2ddf27e1fe63d8309abebfc18f69579a2ab93850e9e
+SHA512:
+  metadata.gz: d97656d46e9618553da42d1e358b500a69141c99693bd588994a518cd900eaa3d1112751aa75f2230c1b84d6b9a76c340e9cd57dd0d130cff4545023b2addb2f
+  data.tar.gz: a09e2707363bf1db60207b82745c47ea4f39680c232561be79b810f7c20599c3317ab9cc37694ea131ba5975bfa338bf3ed599626249cfe39ff1304479694851

data/README.md

@@ -0,0 +1,324 @@
+# Preverus Ruby
+
+Ruby client for Preverus backend enforcement.
+
+Use this gem with Rails, Rack, Sinatra, Hanami, or any Ruby backend that loads the hosted Preverus browser script and needs trusted server-side fraud decisions.
+
+## Install
+
+Add to your Gemfile:
+
+```ruby
+gem "preverus"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Requires Ruby 3.0+.
+
+## Browser And Server Flow
+
+Add the hosted script to your layout:
+
+```html
+<script
+  src="https://cdn.preverus.com/v1/preverus.js"
+  data-preverus-key="pk_live_xxx"
+  data-preverus-auto="true"
+  data-preverus-track-forms="true"
+></script>
+
+<form method="POST" action="/register" data-preverus-action="signup">
+  <input name="email" type="email">
+  <button type="submit">Create account</button>
+</form>
+```
+
+Before submit, the script attaches:
+
+```text
+preverus_fingerprint
+preverus_visitor_id
+preverus_risk_session_token
+preverus_browser_session_event_id
+```
+
+Your backend sends those values to Preverus with a private server key before approving sensitive actions.
+
+## Quick Start
+
+```ruby
+require "preverus"
+
+client = Preverus::Client.new(server_key: ENV.fetch("PREVERUS_SERVER_KEY"))
+
+decision = client.decisions.evaluate(
+  {
+    event_type: "signup",
+    user_id: "acct_42",
+    ip: request.remote_ip,
+    risk_session_token: params[:preverus_risk_session_token],
+    fingerprint: params[:preverus_fingerprint],
+    metadata: {
+      email: params[:email],
+      browser_session_event_id: params[:preverus_browser_session_event_id]
+    }
+  },
+  visitor_id: params[:preverus_visitor_id],
+  idempotency_key: "signup:acct_42:request-id"
+)
+
+if decision.block?
+  head :forbidden
+  return
+end
+
+if decision.review?
+  redirect_to verify_path
+  return
+end
+
+# Continue signup.
+```
+
+Prefer `risk_session_token` when available. It links the backend action to the browser session collected moments earlier.
+
+## Configuration
+
+```ruby
+client = Preverus::Client.new(
+  server_key: ENV.fetch("PREVERUS_SERVER_KEY"),
+  endpoint: "https://api.preverus.com",
+  timeout: 1.5,
+  retries: 2,
+  retry_delay: 0.15,
+  max_retry_delay: 1.0
+)
+```
+
+The gem retries transient network failures and retryable statuses:
+
+```text
+408, 409, 425, 429, 500, 502, 503, 504
+```
+
+It does not retry validation or authentication errors such as `400`, `401`, `403`, or `422`.
+
+Use idempotency keys for retried POST requests.
+
+## Rails Setup
+
+Create an initializer:
+
+```ruby
+# config/initializers/preverus.rb
+PREVERUS = Preverus::Client.new(
+  server_key: ENV.fetch("PREVERUS_SERVER_KEY"),
+  timeout: 1.5,
+  retries: 2
+)
+```
+
+Use it in a controller:
+
+```ruby
+class RegistrationsController < ApplicationController
+  def create
+    decision = PREVERUS.decisions.evaluate(
+      {
+        event_type: "signup",
+        user_id: params[:user_id],
+        ip: request.remote_ip,
+        risk_session_token: params[:preverus_risk_session_token],
+        fingerprint: params[:preverus_fingerprint],
+        metadata: {
+          email: params[:email],
+          user_agent: request.user_agent,
+          browser_session_event_id: params[:preverus_browser_session_event_id]
+        }
+      },
+      visitor_id: params[:preverus_visitor_id],
+      idempotency_key: request.request_id
+    )
+
+    return head :forbidden if decision.block?
+    return redirect_to verify_path if decision.review?
+
+    # Continue registration.
+  end
+end
+```
+
+## Sensitive Actions
+
+Use decisions synchronously when your app needs an immediate allow/review/block answer:
+
+```ruby
+decision = PREVERUS.decisions.evaluate(
+  {
+    event_type: "withdraw",
+    user_id: current_user.id,
+    ip: request.remote_ip,
+    risk_session_token: params[:preverus_risk_session_token],
+    metadata: {
+      payment_address: params[:payment_address]
+    }
+  },
+  visitor_id: params[:preverus_visitor_id],
+  idempotency_key: request.request_id
+)
+
+return head :forbidden if decision.block?
+return redirect_to withdraw_review_path if decision.review?
+```
+
+Good event names include:
+
+```text
+signup
+login
+checkout
+password_reset
+payout
+withdraw
+payment_change
+account_update
+```
+
+## Decisions
+
+```ruby
+decision.recommended_action
+decision.allow?
+decision.review?
+decision.block?
+decision.to_h
+```
+
+Recommended handling:
+
+```text
+allow  -> proceed
+review -> step-up auth, hold, or manual review
+block  -> deny or hard challenge
+```
+
+## Events
+
+Use events for non-blocking fraud telemetry:
+
+```ruby
+event = PREVERUS.events.create(
+  {
+    event_type: "login",
+    user_id: "acct_42",
+    ip: "203.0.113.10",
+    fingerprint: "fp_hash",
+    metadata: { email: "person@example.com" }
+  },
+  visitor_id: "v_abc123"
+)
+```
+
+In Rails, send non-blocking events from Active Job or a background worker so customer requests do not wait for telemetry.
+
+## Lookups
+
+```ruby
+visitor = PREVERUS.visitors.lookup(visitor_id: "v_abc123")
+visitor = PREVERUS.visitors.lookup(fingerprint: "fp_hash")
+
+metadata = PREVERUS.metadata.lookup("email", "person@example.com")
+graph = PREVERUS.metadata.graph("v_abc123")
+```
+
+Use lookups for investigation and context. Use `decisions.evaluate` for final enforcement.
+
+## Webhook Verification
+
+```ruby
+class PreverusWebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def create
+    raw_body = request.raw_post
+    valid = PREVERUS.webhooks.verify(
+      raw_body: raw_body,
+      timestamp: request.headers["X-Fraud-Webhook-Timestamp"].to_s,
+      signature_header: request.headers["X-Fraud-Webhook-Signature"].to_s,
+      secret: ENV.fetch("PREVERUS_WEBHOOK_SECRET")
+    )
+
+    return head :bad_request unless valid
+
+    payload = JSON.parse(raw_body)
+
+    # Store payload["id"] or X-Fraud-Webhook-Id for idempotency.
+
+    head :no_content
+  end
+end
+```
+
+Webhook delivery is at-least-once. Dedupe by `X-Fraud-Webhook-Id` or payload `id`.
+
+You can also verify, parse, and dispatch by event type:
+
+```ruby
+event = PREVERUS.webhooks.construct_event(
+  raw_body: request.raw_post,
+  headers: request.headers,
+  secret: ENV.fetch("PREVERUS_WEBHOOK_SECRET")
+)
+
+return head :no_content if already_processed?(event.id)
+
+PREVERUS.webhooks.dispatch(event, {
+  "decision.high_risk" => ->(event) { open_case(event.to_h) },
+  "*" => ->(event) { Rails.logger.info("Preverus webhook #{event.type}") }
+})
+```
+
+The gem verifies and parses the event, but your app should store processed event IDs in your database or cache.
+
+## Failure Handling
+
+The Ruby core gem raises exceptions for API and network failures:
+
+```ruby
+begin
+  decision = PREVERUS.decisions.evaluate(...)
+rescue Preverus::ApiError => error
+  Rails.logger.warn("Preverus API error: #{error.status_code} #{error.error_code}")
+rescue Preverus::NetworkError
+  # Apply your app's fail-open, fail-review, or fail-closed policy.
+end
+```
+
+For high-risk flows like withdrawals and payouts, a common policy is fail-review. For signup/login/checkout, many businesses prefer fail-open so the site keeps working during transient network failures.
+
+Example fail-review wrapper:
+
+```ruby
+def evaluate_or_review(input, **options)
+  PREVERUS.decisions.evaluate(input, **options)
+rescue Preverus::Error => error
+  Rails.logger.warn("Preverus fallback review: #{error.class}")
+  Preverus::DecisionResult.fallback("review", error.class.name)
+end
+```
+
+## Production Checklist
+
+- Keep `PREVERUS_SERVER_KEY` private.
+- Use a browser key only in templates/frontend code.
+- Prefer `risk_session_token` when present.
+- Include `visitor_id` through the client argument.
+- Send your real customer account ID as `user_id`.
+- Include IP and metadata such as email, phone, username, and payment address.
+- Use idempotency keys for retried POST requests.
+- Treat `review` as step-up/manual review, not as automatic allow.

data/lib/preverus/client.rb

@@ -0,0 +1,24 @@
+require_relative "http_client"
+require_relative "resources"
+
+module Preverus
+  class Client
+    attr_reader :decisions, :events, :visitors, :metadata, :webhooks
+
+    def initialize(server_key:, endpoint: "https://api.preverus.com", timeout: 1.5, retries: 2, retry_delay: 0.15, max_retry_delay: 1.0)
+      http = HttpClient.new(
+        server_key: server_key,
+        endpoint: endpoint,
+        timeout: timeout,
+        retries: retries,
+        retry_delay: retry_delay,
+        max_retry_delay: max_retry_delay
+      )
+      @decisions = Decisions.new(http)
+      @events = Events.new(http)
+      @visitors = Visitors.new(http)
+      @metadata = Metadata.new(http)
+      @webhooks = Webhooks.new
+    end
+  end
+end

data/lib/preverus/errors.rb

@@ -0,0 +1,16 @@
+module Preverus
+  class Error < StandardError; end
+
+  class NetworkError < Error; end
+
+  class ApiError < Error
+    attr_reader :status_code, :error_code, :response
+
+    def initialize(message, status_code: 0, error_code: "api_error", response: {})
+      super(message)
+      @status_code = status_code
+      @error_code = error_code
+      @response = response
+    end
+  end
+end

data/lib/preverus/http_client.rb

@@ -0,0 +1,91 @@
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+require_relative "errors"
+
+module Preverus
+  class HttpClient
+    RETRYABLE_STATUSES = [408, 409, 425, 429, 500, 502, 503, 504].freeze
+
+    def initialize(server_key:, endpoint:, timeout:, retries:, retry_delay:, max_retry_delay:)
+      @server_key = server_key.to_s.strip
+      @endpoint = endpoint.to_s.sub(%r{/+$}, "")
+      @timeout = timeout
+      @retries = [retries.to_i, 0].max
+      @retry_delay = retry_delay
+      @max_retry_delay = max_retry_delay
+    end
+
+    def get(path, params = {}, headers = {})
+      query = URI.encode_www_form(params.reject { |_key, value| value.nil? || value == "" })
+      request("GET", query.empty? ? path : "#{path}?#{query}", nil, headers)
+    end
+
+    def post(path, body, headers = {})
+      request("POST", path, body, headers)
+    end
+
+    private
+
+    def request(method, path, body, headers)
+      raise ApiError.new("Missing Preverus server key.", error_code: "missing_server_key") if @server_key.empty?
+
+      attempts = @retries + 1
+      attempt = 1
+      begin
+        send_request(method, path, body, headers)
+      rescue NetworkError
+        raise if attempt >= attempts
+
+        sleep_before_retry(attempt)
+        attempt += 1
+        retry
+      rescue ApiError => error
+        raise if !RETRYABLE_STATUSES.include?(error.status_code) || attempt >= attempts
+
+        sleep_before_retry(attempt)
+        attempt += 1
+        retry
+      end
+    end
+
+    def send_request(method, path, body, headers)
+      uri = URI.parse("#{@endpoint}/#{path.sub(%r{^/+}, "")}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+
+      request = method == "GET" ? Net::HTTP::Get.new(uri) : Net::HTTP::Post.new(uri)
+      request["Accept"] = "application/json"
+      request["Content-Type"] = "application/json"
+      request["User-Agent"] = "preverus-ruby/0.1"
+      request["X-API-Key"] = @server_key
+      headers.each { |key, value| request[key] = value if value && value != "" }
+      request.body = JSON.generate(body) if body
+
+      response = http.request(request)
+      decoded = response.body.to_s.empty? ? {} : JSON.parse(response.body)
+      status = response.code.to_i
+      raise api_error(status, decoded) unless status.between?(200, 299)
+
+      decoded
+    rescue JSON::ParserError
+      raise ApiError.new("Preverus returned invalid JSON.", error_code: "invalid_json")
+    rescue Timeout::Error, SocketError, SystemCallError, OpenSSL::SSL::SSLError => error
+      raise NetworkError, "Unable to connect to Preverus: #{error.message}"
+    end
+
+    def api_error(status, decoded)
+      message = decoded.is_a?(Hash) && decoded["message"].is_a?(String) ? decoded["message"] : "Preverus API error."
+      code = decoded.is_a?(Hash) && decoded["code"].is_a?(String) ? decoded["code"] : "api_error"
+      ApiError.new(message, status_code: status, error_code: code, response: decoded.is_a?(Hash) ? decoded : {})
+    end
+
+    def sleep_before_retry(attempt)
+      base = [@max_retry_delay, @retry_delay * (2**[attempt - 1, 0].max)].min
+      sleep(base + rand * (base / 2.0))
+    end
+  end
+end

data/lib/preverus/resources.rb

@@ -0,0 +1,99 @@
+require "openssl"
+require "json"
+require_relative "results"
+
+module Preverus
+  class Decisions
+    def initialize(http)
+      @http = http
+    end
+
+    def evaluate(input, visitor_id: nil, idempotency_key: nil, headers: {})
+      request_headers = headers.dup
+      request_headers["X-Visitor-ID"] = visitor_id if visitor_id && visitor_id != ""
+      request_headers["X-Idempotency-Key"] = idempotency_key if idempotency_key && idempotency_key != ""
+      DecisionResult.new(@http.post("/v1/decision/evaluate", input, request_headers))
+    end
+  end
+
+  class Events
+    def initialize(http)
+      @http = http
+    end
+
+    def create(input, visitor_id: nil, idempotency_key: nil)
+      headers = {}
+      headers["X-Visitor-ID"] = visitor_id if visitor_id && visitor_id != ""
+      headers["X-Idempotency-Key"] = idempotency_key if idempotency_key && idempotency_key != ""
+      ApiResult.new(@http.post("/v1/events", input, headers))
+    end
+  end
+
+  class Visitors
+    def initialize(http)
+      @http = http
+    end
+
+    def lookup(visitor_id: nil, fingerprint: nil, ip: nil)
+      ApiResult.new(@http.get("/v1/score/visitors/lookup", { visitor_id: visitor_id, fingerprint: fingerprint, ip: ip }))
+    end
+  end
+
+  class Metadata
+    def initialize(http)
+      @http = http
+    end
+
+    def lookup(key, value, include_global: true, visitor_limit: 20)
+      ApiResult.new(@http.get("/v1/score/metadata/lookup", {
+        key: key,
+        value: value,
+        include_global: include_global ? "true" : "false",
+        visitor_limit: visitor_limit
+      }))
+    end
+
+    def graph(visitor_id, limit: 50)
+      ApiResult.new(@http.get("/v1/score/metadata/graph", { visitor_id: visitor_id, limit: limit }))
+    end
+  end
+
+  class Webhooks
+    def verify(raw_body:, timestamp:, signature_header:, secret:, tolerance_seconds: 300)
+      return false if timestamp.to_s !~ /\A\d+\z/ || signature_header.to_s.empty? || secret.to_s.empty?
+      return false if (Time.now.to_i - timestamp.to_i).abs > tolerance_seconds
+
+      expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{raw_body}")
+      received = signature_header.to_s.sub(/\Av1=/, "").strip
+      secure_compare(expected, received)
+    end
+
+    def construct_event(raw_body:, headers:, secret:, tolerance_seconds: 300)
+      timestamp = headers["X-Fraud-Webhook-Timestamp"] || headers["x-fraud-webhook-timestamp"] || ""
+      signature = headers["X-Fraud-Webhook-Signature"] || headers["x-fraud-webhook-signature"] || ""
+      unless verify(raw_body: raw_body, timestamp: timestamp, signature_header: signature, secret: secret, tolerance_seconds: tolerance_seconds)
+        raise ArgumentError, "Invalid Preverus webhook signature."
+      end
+
+      payload = JSON.parse(raw_body)
+      raise ArgumentError, "Invalid Preverus webhook JSON payload." unless payload.is_a?(Hash)
+
+      WebhookEvent.new(payload, raw_body)
+    end
+
+    def dispatch(event, handlers)
+      handler = handlers[event.type] || handlers["*"]
+      return nil unless handler.respond_to?(:call)
+
+      handler.call(event)
+    end
+
+    private
+
+    def secure_compare(expected, received)
+      return false unless expected.bytesize == received.bytesize
+
+      expected.bytes.zip(received.bytes).reduce(0) { |memo, (left, right)| memo | (left ^ right) }.zero?
+    end
+  end
+end

data/lib/preverus/results.rb

@@ -0,0 +1,82 @@
+module Preverus
+  class ApiResult
+    attr_reader :data
+
+    def initialize(data)
+      @data = data || {}
+    end
+
+    def [](key)
+      @data[key.to_s] || @data[key.to_sym]
+    end
+
+    def to_h
+      @data.dup
+    end
+  end
+
+  class DecisionResult < ApiResult
+    attr_reader :failure_reason
+
+    def initialize(data, fallback: false, failure_reason: nil)
+      super(data)
+      @fallback = fallback
+      @failure_reason = failure_reason
+    end
+
+    def self.fallback(action, reason)
+      new(
+        {
+          "recommended_action" => action,
+          "risk_tier" => action == "allow" ? "unknown" : "review",
+          "reasons" => [
+            {
+              "code" => "preverus_unavailable",
+              "severity" => action == "allow" ? "low" : "medium",
+              "message" => "Preverus was unavailable; fallback policy was applied."
+            }
+          ]
+        },
+        fallback: true,
+        failure_reason: reason
+      )
+    end
+
+    def recommended_action
+      self["recommended_action"] || self["action"] || "review"
+    end
+
+    def allow?
+      recommended_action == "allow"
+    end
+
+    def review?
+      recommended_action == "review"
+    end
+
+    def block?
+      ["block", "deny"].include?(recommended_action)
+    end
+
+    def fallback?
+      @fallback
+    end
+  end
+
+  class WebhookEvent < ApiResult
+    attr_reader :raw_body
+
+    def initialize(data, raw_body)
+      super(data)
+      @raw_body = raw_body
+    end
+
+    def id
+      self["id"].to_s
+    end
+
+    def type
+      self["type"].to_s
+    end
+  end
+end

data/lib/preverus.rb

@@ -0,0 +1,6 @@
+require_relative "preverus/client"
+require_relative "preverus/errors"
+require_relative "preverus/results"
+
+module Preverus
+end

data/preverus.gemspec

@@ -0,0 +1,16 @@
+Gem::Specification.new do |spec|
+  spec.name = "preverus"
+  spec.version = "0.1.0"
+  spec.authors = ["Preverus"]
+  spec.summary = "Ruby client for Preverus fraud decisions, events, lookups, and webhooks."
+  spec.description = "Framework-agnostic Ruby client for Preverus backend fraud enforcement."
+  spec.homepage = "https://preverus.com"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0"
+  spec.files = Dir["lib/**/*.rb", "README.md", "LICENSE*", "preverus.gemspec"]
+  spec.require_paths = ["lib"]
+  spec.metadata = {
+    "source_code_uri" => "https://github.com/preverus/preverus-ruby",
+    "documentation_uri" => "https://preverus.com/docs"
+  }
+end

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification
+name: preverus
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Preverus
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Framework-agnostic Ruby client for Preverus backend fraud enforcement.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/preverus.rb
+- lib/preverus/client.rb
+- lib/preverus/errors.rb
+- lib/preverus/http_client.rb
+- lib/preverus/resources.rb
+- lib/preverus/results.rb
+- preverus.gemspec
+homepage: https://preverus.com
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/preverus/preverus-ruby
+  documentation_uri: https://preverus.com/docs
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Ruby client for Preverus fraud decisions, events, lookups, and webhooks.
+test_files: []