private_captcha 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8d114ffe4accff4d744e8a31c2a4db2e19a8415536f90edb03646c84a7d00c16
+  data.tar.gz: ac3306f495d28e9af4fde26cc041384ae6fe921755df621dbccca5691235fd17
+SHA512:
+  metadata.gz: 3c649faf68705a6eda2bb2e3a93337b2b30269cd91f48b629dd704f9e950b9f882f63b69ff57287e32c540be78b8c35d7714f3f763c7983e95675790106bc014
+  data.tar.gz: 4e8aa3fc7a92b88f83085f950438a3cae213c8d41c454b19f947b67531ba3e21f75cc3f3a1b8ea49a139e594272c60b0f7c943b774a2d4bb62765f77db204e69

data/LICENSE

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

data/README.md

@@ -0,0 +1,165 @@
+# private-captcha-ruby
+
+![CI](https://github.com/PrivateCaptcha/private-captcha-ruby/actions/workflows/ci.yaml/badge.svg)
+
+Ruby client for server-side verification of Private Captcha solutions.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'private_captcha'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install private_captcha
+```
+
+## Quick Start
+
+```ruby
+require 'private_captcha'
+
+# Initialize the client with your API key
+client = PrivateCaptcha::Client.new do |config|
+  config.api_key = 'your-api-key-here'
+end
+
+# Verify a captcha solution
+begin
+  result = client.verify('user-solution-from-frontend')
+  if result.success
+    puts 'Captcha verified successfully!'
+  else
+    puts "Verification failed: #{result.error_message}"
+  end
+rescue PrivateCaptcha::Error => e
+  puts "Error: #{e.message}"
+end
+```
+
+## Usage
+
+### Web Framework Integration
+
+#### Sinatra Example
+
+```ruby
+require 'sinatra'
+require 'private_captcha'
+
+client = PrivateCaptcha::Client.new do |config|
+  config.api_key = 'your-api-key'
+end
+
+post '/submit' do
+  begin
+    # Verify captcha from form data
+    client.verify_request(request)
+
+    # Process your form data here
+    'Form submitted successfully!'
+  rescue PrivateCaptcha::Error
+    status 400
+    'Captcha verification failed'
+  end
+end
+```
+
+#### Rails Example
+
+```ruby
+class FormsController < ApplicationController
+  def submit
+    client = PrivateCaptcha::Client.new do |config|
+      config.api_key = 'your-api-key'
+    end
+
+    begin
+      client.verify_request(request)
+      # Process form data
+      render plain: 'Success!'
+    rescue PrivateCaptcha::Error
+      render plain: 'Captcha failed', status: :bad_request
+    end
+  end
+end
+```
+
+#### Rack Middleware
+
+```ruby
+require 'private_captcha'
+
+use PrivateCaptcha::Middleware,
+  api_key: 'your-api-key',
+  failed_status_code: 403
+```
+
+## Configuration
+
+### Client Options
+
+```ruby
+require 'private_captcha'
+
+client = PrivateCaptcha::Client.new do |config|
+  config.api_key = 'your-api-key'
+  config.domain = PrivateCaptcha::Configuration::EU_DOMAIN  # replace domain for self-hosting or EU isolation
+  config.form_field = 'private-captcha-solution'            # custom form field name
+  config.max_backoff_seconds = 20                           # maximum wait between retries
+  config.attempts = 5                                       # number of retry attempts
+  config.logger = Logger.new(STDOUT)                        # optional logger
+end
+```
+
+### Non-standard backend domains
+
+```ruby
+require 'private_captcha'
+
+# Use EU domain
+eu_client = PrivateCaptcha::Client.new do |config|
+  config.api_key = 'your-api-key'
+  config.domain = PrivateCaptcha::Configuration::EU_DOMAIN  # api.eu.privatecaptcha.com
+end
+
+# Or specify custom domain in case of self-hosting
+custom_client = PrivateCaptcha::Client.new do |config|
+  config.api_key = 'your-api-key'
+  config.domain = 'your-custom-domain.com'
+end
+```
+
+### Retry Configuration
+
+```ruby
+result = client.verify(
+  'solution',
+  max_backoff_seconds: 15,  # maximum wait between retries
+  attempts: 3               # number of retry attempts
+)
+```
+
+## Requirements
+
+- Ruby 3.0+
+- No external dependencies (uses only standard library)
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Support
+
+For issues with this Ruby client, please open an issue on GitHub.
+For Private Captcha service questions, visit [privatecaptcha.com](https://privatecaptcha.com).

data/lib/private_captcha/client.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+require 'logger'
+require 'timeout'
+
+module PrivateCaptcha
+  # Client is the main class for verifying Private Captcha solutions
+  class Client # rubocop:disable Metrics/ClassLength
+    MIN_BACKOFF_MILLIS = 500
+
+    attr_reader :config
+
+    def initialize
+      @config = Configuration.new
+      yield(@config) if block_given?
+
+      raise EmptyAPIKeyError if @config.api_key.nil? || @config.api_key.empty?
+
+      @config.domain = normalize_domain(@config.domain)
+      @endpoint = URI("https://#{@config.domain}/verify")
+      @logger = @config.logger || Logger.new(IO::NULL)
+    end
+
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+    def verify(solution, max_backoff_seconds: nil, attempts: nil)
+      raise EmptySolutionError if solution.nil? || solution.empty?
+
+      max_backoff = max_backoff_seconds || @config.max_backoff_seconds
+      max_attempts = attempts || @config.attempts
+
+      @logger.debug('About to start verifying solution') do
+        "maxAttempts=#{max_attempts} maxBackoff=#{max_backoff} solution_length=#{solution.length}"
+      end
+
+      response = nil
+      error = nil
+      attempt = 0
+
+      max_attempts.times do |i|
+        attempt = i + 1
+
+        if i.positive?
+          backoff_duration = calculate_backoff(i, max_backoff, error)
+          @logger.debug('Failed to send verify request') do
+            "attempt=#{attempt} backoff=#{backoff_duration}s error=#{error&.message}"
+          end
+          sleep(backoff_duration)
+        end
+
+        begin
+          response = do_verify(solution)
+          error = nil
+          break
+        rescue RetriableError => e
+          error = e.original_error
+        end
+      end
+
+      @logger.debug('Finished verifying solution') do
+        "attempts=#{attempt} success=#{error.nil?}"
+      end
+
+      if error
+        @logger.error("Failed to verify solution after #{attempt} attempts")
+        raise VerificationFailedError.new("Failed to verify solution after #{attempt} attempts", attempt)
+      end
+
+      response
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+    def verify_request(request, form_field: nil)
+      field = form_field || @config.form_field
+      solution = extract_form_value(request, field)
+
+      output = verify(solution)
+
+      raise Error, "captcha verification failed: #{output.error_message}" unless output.success
+
+      output
+    end
+
+    private
+
+    def normalize_domain(domain)
+      return Configuration::GLOBAL_DOMAIN if domain.nil? || domain.empty?
+
+      domain = domain.delete_prefix('https://')
+      domain = domain.delete_prefix('http://')
+      domain.delete_suffix('/')
+    end
+
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    def do_verify(solution)
+      request = Net::HTTP::Post.new(@endpoint)
+      request['X-Api-Key'] = @config.api_key
+      request['User-Agent'] = "private-captcha-ruby/#{VERSION}"
+      request['Content-Type'] = 'text/plain'
+      request.body = solution
+
+      @logger.debug('Sending HTTP request') { "path=#{@endpoint.path} method=POST" }
+
+      response = nil
+      begin
+        response = Net::HTTP.start(@endpoint.hostname, @endpoint.port, use_ssl: true) do |http|
+          http.request(request)
+        end
+      rescue SocketError, IOError, Timeout::Error, SystemCallError => e
+        @logger.debug('Failed to send HTTP request') { "error=#{e.message}" }
+        raise RetriableError, e
+      end
+
+      @logger.debug('HTTP request finished') do
+        "path=#{@endpoint.path} status=#{response.code}"
+      end
+
+      status_code = response.code.to_i
+      request_id = response['X-Trace-ID']
+
+      case status_code
+      when 429
+        retry_after = parse_retry_after(response['Retry-After'])
+        @logger.debug('Rate limited') do
+          "retryAfter=#{retry_after} rateLimit=#{response['X-RateLimit-Limit']}"
+        end
+        raise RetriableError, HTTPError.new(status_code, retry_after)
+      when 500, 502, 503, 504, 408, 425
+        raise RetriableError, HTTPError.new(status_code)
+      when 300..599
+        raise HTTPError, status_code
+      end
+
+      begin
+        json_data = JSON.parse(response.body)
+        VerifyOutput.from_json(json_data, request_id: request_id)
+      rescue JSON::ParserError => e
+        @logger.debug('Failed to parse response') { "error=#{e.message}" }
+        raise RetriableError, e
+      end
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+    def parse_retry_after(header)
+      return nil if header.nil? || header.empty?
+
+      Integer(header)
+    rescue ArgumentError
+      nil
+    end
+
+    def calculate_backoff(attempt, max_backoff, error)
+      backoff = (MIN_BACKOFF_MILLIS / 1000.0) * (2**attempt)
+
+      backoff = [backoff, error.seconds].max if error.is_a?(HTTPError) && error.seconds
+
+      [backoff, max_backoff].min
+    end
+
+    def extract_form_value(request, field)
+      # Support for Rack::Request
+      if request.respond_to?(:params)
+        request.params[field]
+      # Support for Rails ActionDispatch::Request
+      elsif request.respond_to?(:[])
+        request[field]
+      end
+    end
+  end
+end

data/lib/private_captcha/configuration.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module PrivateCaptcha
+  # Configuration holds the settings for the Private Captcha client
+  class Configuration
+    GLOBAL_DOMAIN = 'api.privatecaptcha.com'
+    EU_DOMAIN = 'api.eu.privatecaptcha.com'
+    DEFAULT_FORM_FIELD = 'private-captcha-solution'
+    DEFAULT_FAILED_STATUS_CODE = 403
+
+    attr_accessor :domain, :api_key, :form_field, :failed_status_code,
+                  :max_backoff_seconds, :attempts, :logger
+
+    def initialize
+      @domain = GLOBAL_DOMAIN
+      @api_key = nil
+      @form_field = DEFAULT_FORM_FIELD
+      @failed_status_code = DEFAULT_FAILED_STATUS_CODE
+      @max_backoff_seconds = 20
+      @attempts = 5
+      @logger = nil
+    end
+  end
+end

data/lib/private_captcha/errors.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module PrivateCaptcha
+  class Error < StandardError; end
+
+  # EmptyAPIKeyError is raised when the API key is not provided or is empty
+  class EmptyAPIKeyError < Error
+    def initialize(msg = 'API key is empty')
+      super
+    end
+  end
+
+  # EmptySolutionError is raised when the solution is not provided or is empty
+  class EmptySolutionError < Error
+    def initialize(msg = 'solution is empty')
+      super
+    end
+  end
+
+  # HTTPError is raised when an HTTP error occurs during verification
+  class HTTPError < Error
+    attr_reader :status_code, :seconds
+
+    def initialize(status_code, seconds = nil)
+      @status_code = status_code
+      @seconds = seconds
+      super("HTTP error #{status_code}")
+    end
+  end
+
+  # RetriableError wraps errors that can be retried
+  class RetriableError < Error
+    attr_reader :original_error
+
+    def initialize(error)
+      @original_error = error
+      super(error.message)
+    end
+  end
+
+  # VerificationFailedError is raised when verification fails after all retry attempts
+  class VerificationFailedError < Error
+    attr_reader :attempts
+
+    def initialize(message, attempts)
+      @attempts = attempts
+      super(message)
+    end
+  end
+end

data/lib/private_captcha/middleware.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'rack'
+
+module PrivateCaptcha
+  # Middleware provides Rack middleware for automatic captcha verification
+  class Middleware
+    # rubocop:disable Metrics/AbcSize
+    def initialize(app, api_key:, **options)
+      @app = app
+      @client = Client.new do |config|
+        config.api_key = api_key
+        config.domain = options[:domain] if options[:domain]
+        config.form_field = options[:form_field] if options[:form_field]
+        config.failed_status_code = options[:failed_status_code] if options[:failed_status_code]
+        config.max_backoff_seconds = options[:max_backoff_seconds] if options[:max_backoff_seconds]
+        config.attempts = options[:attempts] if options[:attempts]
+        config.logger = options[:logger] if options[:logger]
+      end
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    # rubocop:disable Metrics/MethodLength
+    def call(env)
+      request = Rack::Request.new(env)
+
+      begin
+        @client.verify_request(request)
+      rescue Error
+        return [
+          @client.config.failed_status_code,
+          { 'Content-Type' => 'text/plain' },
+          [Rack::Utils::HTTP_STATUS_CODES[@client.config.failed_status_code]]
+        ]
+      end
+
+      @app.call(env)
+    end
+    # rubocop:enable Metrics/MethodLength
+  end
+end

data/lib/private_captcha/verify_output.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module PrivateCaptcha
+  # VerifyOutput represents the result of a captcha verification
+  class VerifyOutput
+    VERIFY_NO_ERROR = 0
+    VERIFY_ERROR_OTHER = 1
+    DUPLICATE_SOLUTIONS_ERROR = 2
+    INVALID_SOLUTION_ERROR = 3
+    PARSE_RESPONSE_ERROR = 4
+    PUZZLE_EXPIRED_ERROR = 5
+    INVALID_PROPERTY_ERROR = 6
+    WRONG_OWNER_ERROR = 7
+    VERIFIED_BEFORE_ERROR = 8
+    MAINTENANCE_MODE_ERROR = 9
+    TEST_PROPERTY_ERROR = 10
+    INTEGRITY_ERROR = 11
+    VERIFY_CODES_COUNT = 12
+
+    ERROR_MESSAGES = {
+      VERIFY_NO_ERROR => '',
+      VERIFY_ERROR_OTHER => 'error-other',
+      DUPLICATE_SOLUTIONS_ERROR => 'solution-duplicates',
+      INVALID_SOLUTION_ERROR => 'solution-invalid',
+      PARSE_RESPONSE_ERROR => 'solution-bad-format',
+      PUZZLE_EXPIRED_ERROR => 'puzzle-expired',
+      INVALID_PROPERTY_ERROR => 'property-invalid',
+      WRONG_OWNER_ERROR => 'property-owner-mismatch',
+      VERIFIED_BEFORE_ERROR => 'solution-verified-before',
+      MAINTENANCE_MODE_ERROR => 'maintenance-mode',
+      TEST_PROPERTY_ERROR => 'property-test',
+      INTEGRITY_ERROR => 'integrity-error'
+    }.freeze
+
+    attr_accessor :success, :code, :origin, :timestamp
+    attr_reader :request_id, :attempt
+
+    def initialize(success: false, code: VERIFY_NO_ERROR, origin: nil, timestamp: nil, request_id: nil, attempt: 0)
+      @success = success
+      @code = code
+      @origin = origin
+      @timestamp = timestamp
+      @request_id = request_id
+      @attempt = attempt
+    end
+
+    def error_message
+      ERROR_MESSAGES.fetch(@code, 'error')
+    end
+
+    def self.from_json(json_data, request_id: nil, attempt: 0)
+      new(
+        success: json_data['success'],
+        code: json_data['code'] || VERIFY_NO_ERROR,
+        origin: json_data['origin'],
+        timestamp: json_data['timestamp'],
+        request_id: request_id,
+        attempt: attempt
+      )
+    end
+  end
+end

data/lib/private_captcha/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PrivateCaptcha
+  VERSION = '0.0.1'
+end

data/lib/private_captcha.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative 'private_captcha/version'
+require_relative 'private_captcha/errors'
+require_relative 'private_captcha/verify_output'
+require_relative 'private_captcha/configuration'
+require_relative 'private_captcha/client'
+require_relative 'private_captcha/middleware'
+
+# PrivateCaptcha is a Ruby client library for integrating Private Captcha
+# verification into your applications. It provides a simple API for verifying
+# captcha solutions and can be used as Rack middleware.
+module PrivateCaptcha
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: private_captcha
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Taras Kushnir
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-10-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: A Ruby library for integrating Private Captcha verification into your
+  applications
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/private_captcha.rb
+- lib/private_captcha/client.rb
+- lib/private_captcha/configuration.rb
+- lib/private_captcha/errors.rb
+- lib/private_captcha/middleware.rb
+- lib/private_captcha/verify_output.rb
+- lib/private_captcha/version.rb
+homepage: https://privatecaptcha.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://privatecaptcha.com
+  source_code_uri: https://github.com/PrivateCaptcha/private-captcha-ruby
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: Ruby client for server-side Private Captcha API
+test_files: []