altcha 1.0.0 → 2.0.0

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", "~> 4.0.1"
-  spec.add_development_dependency "rake", "~> 13.3.1"
-  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