altcha 0.2.0 → 2.0.0

data/SECURITY.md

@@ -0,0 +1,57 @@
+## Security Vulnerability Disclosure Policy
+
+We take security seriously and value the contributions of researchers who act in good faith to help protect our users. If you believe you have found a vulnerability in our services or software, we encourage you to report it responsibly so we can address it promptly.
+
+### Reporting a Vulnerability
+
+Please email your findings to our [security contacts](https://altcha.org/contact#reporting-security-issues).
+To ensure confidentiality, we recommend encrypting your report using our [PGP key](https://altcha.org/pgp/security-public-key.asc).
+
+Your report should include:
+
+- A clear description of the vulnerability.
+- A working proof of concept or detailed steps to reproduce the issue.
+- Relevant logs, screenshots, or code snippets.
+
+We will acknowledge receipt of your report within 5 business days and keep you informed about our investigation.
+
+### In-Scope
+
+We prioritize reports that demonstrate a real, actionable security risk to our software, services, or infrastructure, such as:
+
+- Remote code execution (RCE)
+- Authentication bypass or privilege escalation
+- Server-side request forgery (SSRF)
+- Cross-site scripting (XSS) or CSRF with significant impact
+
+### Out-of-Scope
+
+To minimize automated noise, the following are generally excluded from our review process:
+
+- Automated results: Reports generated by scanners that lack a manual, actionable proof of exploitability.
+- Configuration & Hygiene: Missing HTTP headers, TLS/SSL configurations, DNS records, or server banners.
+- Volume-based attacks: Denial of Service (DoS/DDoS) or rate-limiting issues.
+- Low-impact: Clickjacking on non-sensitive pages, or bugs requiring jailbroken devices/unsupported browsers.
+- Third-party: Issues in libraries or services not directly managed by us.
+
+### Responsible Disclosure Guidelines
+
+To remain in good standing with our team, we ask that you:
+
+- Do not publicly disclose vulnerabilities before we have confirmed a fix.
+- Do not access, modify, or delete data that does not belong to you.
+- Avoid any actions that could degrade or disrupt our services.
+
+We appreciate the efforts of the security community in helping us maintain a safe environment.
+
+### Disclaimer
+
+This is a voluntary disclosure program rooted in the spirit of open-source collaboration. We operate this program to benefit the broader community and ensure the collective safety of our users. We do not offer any form of compensation for submitted reports. By submitting a report, you acknowledge that you are doing so without expectation of payment and waive any future claims for compensation.
+
+### Related
+
+- [Security Advisory](https://altcha.org/security-advisory)
+
+---
+
+Updated: Feb 4, 2026

data/altcha.gemspec

@@ -12,6 +12,7 @@ Gem::Specification.new do |spec|
   spec.description   = "A lightweight library for creating and verifying ALTCHA challenges."
   spec.homepage      = "https://altcha.org"
   spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.7"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -22,7 +23,9 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 2.5"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_dependency "base64"
+
+  spec.add_development_dependency "bundler", "~> 4.0"
+  spec.add_development_dependency "rake", "~> 13.3"
+  spec.add_development_dependency "rspec", "~> 3.13"
 end

data/examples/server.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+# Basic HTTP server demonstrating ALTCHA v2 challenge/verify flow.
+#
+# Usage:
+#   HMAC_SECRET=your-secret ruby examples/server.rb
+#
+# Endpoints:
+#   GET  /challenge  — issues a new challenge (JSON)
+#   POST /submit     — verifies an altcha payload from a form or JSON body
+#
+# Requires:
+#   gem install webrick
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+require 'webrick'
+require 'json'
+require 'base64'
+require 'securerandom'
+require 'uri'
+require 'altcha'
+
+HMAC_SECRET     = ENV.fetch('HMAC_SECRET', 'change-me-in-production')
+HMAC_KEY_SECRET = ENV.fetch('HMAC_KEY_SECRET', 'change-me-in-production')
+PORT            = ENV.fetch('PORT', 3000).to_i
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def cors_headers(response)
+  response['Access-Control-Allow-Origin']  = '*'
+  response['Access-Control-Allow-Methods'] = 'GET, POST, OPTIONS'
+  response['Access-Control-Allow-Headers'] = 'Content-Type'
+end
+
+def json_response(response, status, body)
+  response.status          = status
+  response['Content-Type'] = 'application/json'
+  response.body            = body.to_json
+end
+
+# ---------------------------------------------------------------------------
+# Server
+# ---------------------------------------------------------------------------
+
+server = WEBrick::HTTPServer.new(
+  Port:        PORT,
+  Logger:      WEBrick::Log.new($stdout, WEBrick::Log::INFO),
+  AccessLog:   [[
+    $stdout,
+    '%{%Y-%m-%dT%H:%M:%S}t %m %U %s'
+  ]]
+)
+
+# ---------------------------------------------------------------------------
+# GET /challenge
+# ---------------------------------------------------------------------------
+
+server.mount_proc '/challenge' do |req, res|
+  cors_headers(res)
+
+  if req.request_method == 'OPTIONS'
+    res.status = 204
+    next
+  end
+
+  unless req.request_method == 'GET'
+    json_response(res, 405, { error: 'Method not allowed' })
+    next
+  end
+
+  options = Altcha::V2::CreateChallengeOptions.new(
+    algorithm:                 'PBKDF2/SHA-256',
+    cost:                      5_000,
+    counter:                   SecureRandom.random_number(5_000..10_000),
+    expires_at:                Time.now + 300,   # 5 minutes
+    hmac_signature_secret:     HMAC_SECRET,
+    hmac_key_signature_secret: HMAC_KEY_SECRET
+  )
+
+  challenge = Altcha::V2.create_challenge(options)
+  json_response(res, 200, challenge.to_h)
+end
+
+# ---------------------------------------------------------------------------
+# POST /submit
+# ---------------------------------------------------------------------------
+
+server.mount_proc '/submit' do |req, res|
+  cors_headers(res)
+
+  if req.request_method == 'OPTIONS'
+    res.status = 204
+    next
+  end
+
+  unless req.request_method == 'POST'
+    json_response(res, 405, { error: 'Method not allowed' })
+    next
+  end
+
+  # Parse the request body based on Content-Type.
+  content_type = req['Content-Type'].to_s
+  form_data    = {}
+  altcha_value = nil
+
+  begin
+    if content_type.include?('application/json')
+      parsed       = JSON.parse(req.body || '{}')
+      altcha_value = parsed.delete('altcha')
+      form_data    = parsed
+
+    elsif content_type.include?('application/x-www-form-urlencoded')
+      parsed       = URI.decode_www_form(req.body || '').to_h
+      altcha_value = parsed.delete('altcha')
+      form_data    = parsed
+
+    else
+      json_response(res, 415, { error: 'Unsupported content type' })
+      next
+    end
+  rescue JSON::ParserError
+    json_response(res, 400, { error: 'Invalid JSON body' })
+    next
+  end
+
+  if altcha_value.nil? || altcha_value.empty?
+    json_response(res, 400, { error: 'Missing altcha field' })
+    next
+  end
+
+  # Decode and verify the ALTCHA payload.
+  # Detect type by presence of 'verificationData' (server signature) vs 'solution' (client payload).
+  begin
+    decoded = JSON.parse(Base64.decode64(altcha_value))
+
+    result = if decoded.key?('verificationData')
+               Altcha::V2.verify_server_signature(
+                 payload:     Altcha::V2::ServerSignaturePayload.from_h(decoded),
+                 hmac_secret: HMAC_SECRET
+               )
+             else
+               payload = Altcha::V2::Payload.new(
+                 challenge: Altcha::V2::Challenge.from_h(decoded['challenge']),
+                 solution:  Altcha::V2::Solution.new(
+                   counter:     decoded['solution']['counter'],
+                   derived_key: decoded['solution']['derivedKey']
+                 )
+               )
+               Altcha::V2.verify_solution(
+                 payload.challenge,
+                 payload.solution,
+                 hmac_signature_secret:     HMAC_SECRET,
+                 hmac_key_signature_secret: HMAC_KEY_SECRET
+               )
+             end
+  rescue StandardError => e
+    json_response(res, 400, { error: "Invalid altcha payload: #{e.message}" })
+    next
+  end
+
+  altcha_result = {
+    verified:          result.verified,
+    expired:           result.expired,
+    invalid_signature: result.invalid_signature,
+    invalid_solution:  result.invalid_solution,
+    time:              result.time
+  }
+  altcha_result[:verification_data] = result.verification_data if result.respond_to?(:verification_data)
+
+  unless result.verified
+    reason = if result.expired
+               'Challenge expired'
+             elsif result.invalid_signature
+               'Invalid challenge signature'
+             else
+               'Incorrect solution'
+             end
+    json_response(res, 400, { error: reason, altcha: altcha_result })
+    next
+  end
+
+  # The form data is now trusted. Process it here.
+  $stdout.puts "Verified submission: #{form_data}"
+
+  json_response(res, 200, { success: true, received: form_data, altcha: altcha_result })
+end
+
+# ---------------------------------------------------------------------------
+# Start
+# ---------------------------------------------------------------------------
+
+trap('INT')  { server.shutdown }
+trap('TERM') { server.shutdown }
+
+$stdout.puts "Listening on http://localhost:#{PORT}"
+$stdout.puts "HMAC_SECRET: #{HMAC_SECRET == 'change-me-in-production' ? '(default — set HMAC_SECRET env var)' : '(set)'}"
+$stdout.puts "HMAC_KEY_SECRET: #{HMAC_KEY_SECRET == 'change-me-in-production' ? '(default — set HMAC_KEY_SECRET env var)' : '(set)'}"
+server.start

data/lib/altcha/v1.rb

@@ -0,0 +1,336 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'base64'
+require 'json'
+require 'uri'
+require 'time'
+
+module Altcha
+  # V1 proof-of-work: find a number N such that SHA256(salt+N) equals the challenge hash.
+  module V1
+    # Contains algorithm type definitions for hashing.
+    module Algorithm
+      SHA1   = 'SHA-1'
+      SHA256 = 'SHA-256'
+      SHA512 = 'SHA-512'
+    end
+
+    DEFAULT_MAX_NUMBER  = 1_000_000
+    DEFAULT_SALT_LENGTH = 12
+    DEFAULT_ALGORITHM   = Algorithm::SHA256
+
+    # Options for generating a challenge.
+    class ChallengeOptions
+      attr_accessor :algorithm, :max_number, :salt_length, :hmac_key, :salt, :number, :expires, :params
+
+      def initialize(algorithm: nil, max_number: nil, salt_length: nil, hmac_key:,
+                     salt: nil, number: nil, expires: nil, params: nil)
+        @algorithm   = algorithm
+        @max_number  = max_number
+        @salt_length = salt_length
+        @hmac_key    = hmac_key
+        @salt        = salt
+        @number      = number
+        @expires     = expires
+        @params      = params
+      end
+    end
+
+    # A challenge sent to the client.
+    class Challenge
+      attr_accessor :algorithm, :challenge, :maxnumber, :salt, :signature
+
+      def initialize(algorithm:, challenge:, maxnumber: nil, salt:, signature:)
+        @algorithm = algorithm
+        @challenge = challenge
+        @maxnumber = maxnumber
+        @salt      = salt
+        @signature = signature
+      end
+
+      def to_json(options = {})
+        {
+          algorithm: @algorithm,
+          challenge: @challenge,
+          maxnumber: @maxnumber,
+          salt:      @salt,
+          signature: @signature
+        }.to_json(options)
+      end
+    end
+
+    # The client-submitted solution payload.
+    class Payload
+      attr_accessor :algorithm, :challenge, :number, :salt, :signature
+
+      def initialize(algorithm:, challenge:, number:, salt:, signature:)
+        @algorithm = algorithm
+        @challenge = challenge
+        @number    = number
+        @salt      = salt
+        @signature = signature
+      end
+
+      def to_json(options = {})
+        {
+          algorithm: @algorithm,
+          challenge: @challenge,
+          number:    @number,
+          salt:      @salt,
+          signature: @signature
+        }.to_json(options)
+      end
+
+      def self.from_json(string)
+        data = JSON.parse(string)
+        new(
+          algorithm: data['algorithm'],
+          challenge: data['challenge'],
+          number:    data['number'],
+          salt:      data['salt'],
+          signature: data['signature']
+        )
+      end
+    end
+
+    # Payload for server-side signature verification.
+    class ServerSignaturePayload
+      attr_accessor :algorithm, :verification_data, :signature, :verified
+
+      def initialize(algorithm:, verification_data:, signature:, verified:)
+        @algorithm         = algorithm
+        @verification_data = verification_data
+        @signature         = signature
+        @verified          = verified
+      end
+
+      def to_json(options = {})
+        {
+          algorithm:        @algorithm,
+          verificationData: @verification_data,
+          signature:        @signature,
+          verified:         @verified
+        }.to_json(options)
+      end
+
+      def self.from_json(string)
+        data = JSON.parse(string)
+        new(
+          algorithm:         data['algorithm'],
+          verification_data: data['verificationData'],
+          signature:         data['signature'],
+          verified:          data['verified']
+        )
+      end
+    end
+
+    # Typed fields returned from verify_server_signature.
+    class ServerSignatureVerificationData
+      attr_accessor :classification, :country, :detected_language, :email, :expire,
+                    :fields, :fields_hash, :ip_address, :reasons, :score, :time, :verified
+
+      def to_json(options = {})
+        {
+          classification:  @classification,
+          country:         @country,
+          detectedLanguage: @detected_language,
+          email:           @email,
+          expire:          @expire,
+          fields:          @fields,
+          fieldsHash:      @fields_hash,
+          ipAddress:       @ip_address,
+          reasons:         @reasons,
+          score:           @score,
+          time:            @time,
+          verified:        @verified
+        }.to_json(options)
+      end
+    end
+
+    # Result of solve_challenge.
+    class Solution
+      attr_accessor :number, :took
+    end
+
+    # -------------------------------------------------------------------------
+    # Module-level functions
+    # -------------------------------------------------------------------------
+
+    def self.random_bytes(length)
+      OpenSSL::Random.random_bytes(length)
+    end
+
+    def self.random_int(max)
+      rand(max + 1)
+    end
+
+    def self.hash_hex(algorithm, data)
+      hash(algorithm, data).unpack1('H*')
+    end
+
+    def self.hash(algorithm, data)
+      case algorithm
+      when Algorithm::SHA1   then OpenSSL::Digest::SHA1.digest(data)
+      when Algorithm::SHA256 then OpenSSL::Digest::SHA256.digest(data)
+      when Algorithm::SHA512 then OpenSSL::Digest::SHA512.digest(data)
+      else raise ArgumentError, "Unsupported algorithm: #{algorithm}"
+      end
+    end
+
+    def self.hmac_hex(algorithm, data, key)
+      hmac_hash(algorithm, data, key).unpack1('H*')
+    end
+
+    def self.hmac_hash(algorithm, data, key)
+      digest_class = case algorithm
+                     when Algorithm::SHA1   then OpenSSL::Digest::SHA1
+                     when Algorithm::SHA256 then OpenSSL::Digest::SHA256
+                     when Algorithm::SHA512 then OpenSSL::Digest::SHA512
+                     else raise ArgumentError, "Unsupported algorithm: #{algorithm}"
+                     end
+      OpenSSL::HMAC.digest(digest_class.new, key, data)
+    end
+
+    def self.create_challenge(options)
+      algorithm   = options.algorithm   || DEFAULT_ALGORITHM
+      max_number  = options.max_number  || DEFAULT_MAX_NUMBER
+      salt_length = options.salt_length || DEFAULT_SALT_LENGTH
+
+      params = options.params || {}
+      params['expires'] = options.expires.to_i if options.expires
+
+      salt = options.salt || random_bytes(salt_length).unpack1('H*')
+      salt += "?#{URI.encode_www_form(params)}" unless params.empty?
+      salt += salt.end_with?('&') ? '' : '&'
+
+      number    = options.number || random_int(max_number)
+      challenge = hash_hex(algorithm, "#{salt}#{number}")
+      signature = hmac_hex(algorithm, challenge, options.hmac_key)
+
+      Challenge.new(
+        algorithm: algorithm,
+        challenge: challenge,
+        maxnumber: max_number,
+        salt:      salt,
+        signature: signature
+      )
+    end
+
+    def self.verify_solution(payload, hmac_key, check_expires = true)
+      if payload.is_a?(String)
+        payload = Payload.from_json(Base64.decode64(payload))
+      elsif payload.is_a?(Hash)
+        payload = Payload.new(
+          algorithm: payload[:algorithm],
+          challenge: payload[:challenge],
+          number:    payload[:number],
+          salt:      payload[:salt],
+          signature: payload[:signature]
+        )
+      end
+
+      return false unless payload.is_a?(Payload)
+
+      %i[algorithm challenge number salt signature].each do |attr|
+        value = payload.send(attr)
+        return false if value.nil? || value.to_s.strip.empty?
+      end
+
+      if check_expires && payload.salt.include?('?')
+        expires = URI.decode_www_form(payload.salt.split('?').last).to_h['expires'].to_i
+        return false if expires && Time.now.to_i > expires
+      end
+
+      expected = create_challenge(
+        ChallengeOptions.new(
+          algorithm: payload.algorithm,
+          hmac_key:  hmac_key,
+          number:    payload.number,
+          salt:      payload.salt
+        )
+      )
+      expected.challenge == payload.challenge && expected.signature == payload.signature
+    rescue ArgumentError, JSON::ParserError
+      false
+    end
+
+    def self.extract_params(payload)
+      URI.decode_www_form(payload.salt.split('?').last).to_h
+    end
+
+    def self.verify_fields_hash(form_data, fields, fields_hash, algorithm)
+      lines       = fields.map { |field| form_data[field].to_s }
+      joined_data = lines.join("\n")
+      hash_hex(algorithm, joined_data) == fields_hash
+    end
+
+    def self.verify_server_signature(payload, hmac_key)
+      if payload.is_a?(String)
+        payload = ServerSignaturePayload.from_json(Base64.decode64(payload))
+      elsif payload.is_a?(Hash)
+        payload = ServerSignaturePayload.new(
+          algorithm:         payload[:algorithm],
+          verification_data: payload[:verification_data],
+          signature:         payload[:signature],
+          verified:          payload[:verified]
+        )
+      end
+
+      return [false, nil] unless payload.is_a?(ServerSignaturePayload)
+
+      %i[algorithm verification_data signature verified].each do |attr|
+        value = payload.send(attr)
+        return false if value.nil? || value.to_s.strip.empty?
+      end
+
+      hash_data         = hash(payload.algorithm, payload.verification_data)
+      expected_signature = hmac_hex(payload.algorithm, hash_data, hmac_key)
+
+      params = URI.decode_www_form(payload.verification_data).to_h
+      verification_data = ServerSignatureVerificationData.new.tap do |v|
+        v.classification    = params['classification']
+        v.country           = params['country']
+        v.detected_language = params['detectedLanguage']
+        v.email             = params['email']
+        v.expire            = params['expire']&.to_i
+        v.fields            = params['fields']&.split(',')
+        v.fields_hash       = params['fieldsHash']
+        v.ip_address        = params['ipAddress']
+        v.reasons           = params['reasons']&.split(',')
+        v.score             = params['score']&.to_f
+        v.time              = params['time']&.to_i
+        v.verified          = params['verified'] == 'true'
+      end
+
+      now = Time.now.to_i
+      is_verified = payload.verified &&
+                    verification_data.verified &&
+                    (verification_data.expire.nil? || verification_data.expire > now) &&
+                    payload.signature == expected_signature
+
+      [is_verified, verification_data]
+    rescue ArgumentError, JSON::ParserError => e
+      puts "Error decoding or parsing payload: #{e.message}"
+      false
+    end
+
+    def self.solve_challenge(challenge, salt, algorithm, max, start)
+      algorithm  ||= DEFAULT_ALGORITHM
+      max        ||= DEFAULT_MAX_NUMBER
+      start      ||= 0
+      start_time   = Time.now
+
+      (start..max).each do |n|
+        if hash_hex(algorithm, "#{salt}#{n}") == challenge
+          return Solution.new.tap do |s|
+            s.number = n
+            s.took   = Time.now - start_time
+          end
+        end
+      end
+
+      nil
+    end
+  end
+end