altcha-rails 0.0.5 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 90110a4f6b3610f15fc055ff3112584ebbce5d95c83bef42edbe1231c8ea8bfa
-  data.tar.gz: 57b70648aca748843334555ef4248b797ec0a4c8afcdb80bdd5e838dd3a147e4
+  metadata.gz: ba8a3f7a187f4b142c1b28a24d9d144b1fe317127df1a318363ff4eed8572acb
+  data.tar.gz: 9f46b25f55a4aaaaa00df542f1a517b1b7d28ba48518f2651b16400c95c65287
 SHA512:
-  metadata.gz: 521a8e5a81fa59babb816ea1ff8b352f57362af59744b01cab0dcb176fd458e899410d7273cd633fe4a8fac4cbce9bda0858b47193c5f1a916c0c51d41158561
-  data.tar.gz: fcbf3c2d8cddaf1dd3e46e101df6334ab32b17ff2ca1da01a7b873a7ff9030f84730756c420f06b75e1ef4b826857ec27dabbc20bf3e7f3379633ee46fb15923
+  metadata.gz: 30e3e105f9d0189b5f86ad0ee6e14fe52989ddf2d08f32750293d8e63316dc1631dfd7b05e0ca0580fcbcfe40f5594bd5a8479290f384fb643f2227257cc8ec4
+  data.tar.gz: 9e59a4d3bb6348fb59999a6bc157f52180aa0895fecc87c4034088d65f0477e6e17db87c373a07a4dd078d8e8f7fa3cd6cc534f976fe889cb50ea1823cf338e0

data/.gitignore

@@ -1,2 +1,3 @@
 /*.gem
+/Gemfile.lock
 

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/README.md

@@ -4,98 +4,228 @@
 
 [ALTCHA](https://altcha.org/) is a protocol designed for safeguarding against spam and abuse by utilizing a proof-of-work mechanism. This protocol comprises both a client-facing widget and a server-side verification process.
 
-`altcha-ruby` is a Ruby gem that provides a simple way to integrate ALTCHA into your Ruby on Rails application.
+`altcha-rails` is a Ruby gem that provides a simple way to integrate ALTCHA into your Ruby on Rails application.
 
-The main functionality of the gem is to generate a challenge and verify the response from the client. This is done in the library code. An initializer and a controller is installed in the host application to handle the challenge generation and verification.
+The gem provides two module methods: `Altcha.create_challenge`, which produces a fresh challenge for the form, and `Altcha.verify`, which validates the widget's submission and records it in `Rails.cache` for replay protection.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'altcha-ruby'
+gem 'altcha-rails'
 ```
 
-Then execute `bundle install` to install the gem for your application.
-
-Next, run the generator to install the initializer and the controller:
-
-```bash
-$ rails generate altcha:install
-      create  app/models/altcha_solution.rb
-      create  app/controllers/altcha_controller.rb
-      create  config/initializers/altcha.rb
-       route  get '/altcha', to: 'altcha#new'
-      create  db/migrate/20240211145410_create_altcha_solutions.rb
-```
-
-This will create an initializer file at `config/initializers/altcha.rb` and a controller at `app/controllers/altcha_controller.rb` as well as a route in `config/routes.rb` and a model at `app/models/altcha-solutions.rb` (see below).
+Then execute `bundle install`.
 
 ## Configuration
 
-The initializer file `config/initializers/altcha.rb` contains the following configuration options:
+Create `config/initializers/altcha.rb` with the following configuration options:
 
 ```ruby
 Altcha.setup do |config|
-  config.algorithm = 'SHA-256'
-  config.num_range = (50_000..500_000)
-  config.timeout = 5.minutes
-  config.hmac_key = 'change-me'
+  config.hmac_key         = ENV.fetch('ALTCHA_HMAC_KEY')
+  config.algorithm        = 'SHA-256'             # default
+  config.max_number       = 1_000_000             # difficulty: upper bound for the proof-of-work nonce. default 1_000_000
+  config.timeout          = 5.minutes             # default 300 seconds; accepts integers or ActiveSupport durations
+  config.cache_key_prefix = 'altcha:solution:'    # default; prepended to the Rails.cache key used for replay protection
 end
 ```
 
-The `algorithm` option specifies the hashing algorithm to use and must currently be set to `SHA-256`.
-It is crucial change the `hmac_key` to a secure value. This key is used to sign the challenge and the response,
-so it must be treated as a secret within your application.
-The `num_range` option specifies the range of numbers to use in the challenge and determines the difficulty of the proof-of-work.
-For an explanation of the `timeout` option see below.
+`hmac_key` has no default — it must be set explicitly. The other options have the defaults shown above.
 
 ## Challenge expiration
 
-The current time of the server is included in the salt of the challenge. When the client responds, it has to send the
-same salt back, so the server can determine when the challenge was issued. The `timeout` option in the initializer file
-specifies the time that a challenge is valid. If the response is received after the timeout, the verification will fail.
+Each challenge embeds an `expires` parameter in its salt — a Unix timestamp set to `Time.now + Altcha.timeout`.
+When the client responds, the server rejects the submission if that timestamp has passed.
+
+The salt is laid out in the canonical v1 ALTCHA format — `<random_hex>?expires=<unix_seconds>&` — including the
+trailing `&` delimiter that closes the parameter list before the proof-of-work nonce is appended for hashing. This
+delimiter is required by the protocol fix for [CVE-2025-68113](https://altcha.org/security-advisory/) and is enforced
+by `Altcha.verify`.
 
 As users might complete the captcha before filling out a complex form, the `timeout` should be set to a reasonable
 value.
 
 ## Replay attacks
 
-To also guard against replay attacks within the configured `timeout` period, the gem uses a model named `AltchaSolution` to
-store completed responses. A unique constraint is added to the database to prevent the same response from being stored.
-
-As these stored solutions are useless after the `timeout` period, the `AltchaSolution.cleanup` convenience function
-should be called regularly.
+To also guard against replay attacks within the configured `timeout` period, the gem records each accepted
+solution in `Rails.cache`, keyed by the solution's HMAC signature. Entries are written with `expires_in: Altcha.timeout`
+and `unless_exist: true`, so a replayed submission within the timeout window is rejected atomically, and entries
+expire automatically once the timeout has passed. No periodic cleanup is required.
 
-## Usage
+Make sure `Rails.cache` is configured to use a backend that is shared across all server processes (e.g.
+`:redis_cache_store`, `:mem_cache_store`, `:solid_cache_store`, or `:file_store`). The default `:memory_store` is
+per-process and would let a replay slip through on a different worker; `:null_store` disables replay protection
+entirely.
 
-You need to include the ALTCHA javascript widget in your application's asset pipeline. This is not done by the gem
-at this point. Read up on the [ALTCHA documentation](https://altcha.org/docs/website-integration) for more information.
+## Issuing a challenge
 
-Add then following code to the form you want to protect:
+`Altcha.create_challenge` returns an `Altcha::Challenge` whose `#to_json` produces exactly the payload the widget expects. The widget accepts this JSON directly via its `challenge` attribute, so no separate `/altcha` route is needed:
 
 ```erb
-<altcha-widget challengeurl="<%= altcha_url() %>"></altcha-widget>
+<altcha-widget challenge='<%= Altcha.create_challenge.to_json %>'></altcha-widget>
 ```
 
-The widget will create a hidden input field with the name `altcha` and the response to the challenge as its value.
+Include the ALTCHA javascript widget script in your asset pipeline; see [the ALTCHA documentation](https://altcha.org/docs/website-integration) for the widget itself.
 
-In the controller that handles the form submission, you can verify the response with the following code:
+## Verifying a submission
+
+When the form is submitted, the widget sends a base64-encoded JSON payload in a hidden input named `altcha`. In the controller that handles the submission, verify it with:
 
 ```ruby
 def create
-  @model = Model.new(model_params)
+  @model = Model.create(model_params)
+
+  unless Altcha.verify(params.permit(:altcha)[:altcha])
+    flash.now[:alert] = 'ALTCHA verification failed.'
+    render :new, status: :unprocessable_entity
+    return
+  end
+
+  # ...
+end
+```
+
+`Altcha.verify` returns the `Altcha::Submission` if the response is valid and has not been seen before within the
+timeout window, and `nil` otherwise.
+
+## Development
+
+```
+bundle install
+bundle exec rake test
+```
+
+Tests use Minitest and a small `FakeCache` shim that mimics the bits of `Rails.cache` the gem touches, so the suite runs without booting Rails.
 
+## Changelog
+
+### 0.1.0
+
+This release is a substantial rework. The public API collapses to two module methods, and everything else (model, migration, controller, route, generator) is gone.
+
+**Highlights:**
+
+- **Security fix — [CVE-2025-68113](https://altcha.org/security-advisory/) (challenge splicing / replay).** Salt now follows the canonical v1 ALTCHA format `<random_hex>?expires=<unix_seconds>&`, and `Altcha.verify` normalises the salt to its trailing-`&` form before recomputing the proof-of-work hash. A spliced salt no longer round-trips to the same digest.
+- **No more `AltchaSolution` ActiveRecord model or `altcha_solutions` table.** Replay protection lives in `Rails.cache` (keyed by the submission's HMAC signature, TTL = `Altcha.timeout`, atomic via `unless_exist: true`).
+- **No more generated controller or route.** The widget now accepts the challenge JSON inline via its `challenge` attribute, so the host application no longer needs an endpoint to serve challenges.
+- **No more `rails generate altcha:install` generator.** Configuration is one `Altcha.setup` block — see [Configuration](#configuration) above.
+- **Configuration knob renamed**: `num_range` (Range) → `max_number` (Integer). `hmac_key` no longer has a placeholder default and must be set explicitly. A new `cache_key_prefix` option (default `"altcha:solution:"`) lets you namespace the replay-tracking keys.
+
+#### Upgrade guide from 0.0.x
+
+**1. Confirm your cache backend.** It must be shared across all server processes. In production: `:redis_cache_store`, `:mem_cache_store`, `:solid_cache_store`, `:file_store`, or another shared backend. The default `:memory_store` is per-process and is unsafe here; `:null_store` disables replay protection entirely. See the [Challenge expiration](#challenge-expiration) section.
+
+**2. Delete the generated model:**
+
+```
+rm app/models/altcha_solution.rb
+```
+
+If you have specs covering it, remove those too.
+
+**3. Delete the generated controller:**
+
+```
+rm app/controllers/altcha_controller.rb
+```
+
+If you have specs or request tests covering it, remove those too.
+
+**4. Remove the route.** In `config/routes.rb`, delete the line:
+
+```ruby
+get '/altcha', to: 'altcha#new'
+```
+
+**5. Update your view to inline the challenge JSON.** Replace:
+
+```erb
+<altcha-widget challengeurl="<%= altcha_url %>"></altcha-widget>
+```
+
+with:
+
+```erb
+<altcha-widget challenge='<%= Altcha.create_challenge.to_json %>'></altcha-widget>
+```
+
+The `challenge` attribute is part of the modern ALTCHA widget; the `challengeurl` round-trip is no longer required.
+
+**6. Generate a migration to drop the `altcha_solutions` table:**
+
+```
+$ rails generate migration DropAltchaSolutions
+```
+
+Fill in the generated file as follows (the `down` block is provided so the migration is reversible — adjust the column list if your installation customised it):
+
+```ruby
+class DropAltchaSolutions < ActiveRecord::Migration[7.1]
+  def up
+    drop_table :altcha_solutions
+  end
+
+  def down
+    create_table :altcha_solutions do |t|
+      t.string  :algorithm
+      t.string  :challenge
+      t.string  :salt
+      t.string  :signature
+      t.integer :number
+
+      t.timestamps
+    end
+
+    add_index :altcha_solutions,
+              [:algorithm, :challenge, :salt, :signature, :number],
+              unique: true,
+              name: 'index_altcha_solutions'
+  end
+end
+```
+
+Then run `rails db:migrate`.
+
+**7. Replace the verification call.** The public API moves from the generated model to the gem itself. The return value flips from boolean to `Altcha::Submission`-or-`nil`, but the truthy/falsy semantics are unchanged:
+
+```ruby
+# Before (0.0.x):
 unless AltchaSolution.verify_and_save(params.permit(:altcha)[:altcha])
   flash.now[:alert] = 'ALTCHA verification failed.'
-  render :new
+  render :new, status: :unprocessable_entity
   return
+end
 
-  # ...
+# After (0.1.0):
+unless Altcha.verify(params.permit(:altcha)[:altcha])
+  flash.now[:alert] = 'ALTCHA verification failed.'
+  render :new, status: :unprocessable_entity
+  return
 end
 ```
 
-The `verify_and_save` method will return `true` if the response is valid and has not been used before.
+**8. Remove `AltchaSolution.cleanup` calls.** Cache entries now expire automatically via `expires_in: Altcha.timeout`, so any scheduled job, rake task, or cron entry that called `AltchaSolution.cleanup` can be deleted.
+
+**9. Update your initializer.** Rename `num_range` to `max_number` (and switch from a Range to an Integer) and remove any placeholder `hmac_key = 'change-me'`:
+
+```ruby
+# Before (0.0.x):
+Altcha.setup do |config|
+  config.algorithm = 'SHA-256'
+  config.num_range = (50_000..500_000)
+  config.timeout   = 5.minutes
+  config.hmac_key  = 'change-me'
+end
+
+# After (0.1.0):
+Altcha.setup do |config|
+  config.hmac_key   = ENV.fetch('ALTCHA_HMAC_KEY')
+  config.max_number = 500_000
+  config.timeout    = 5.minutes
+end
+```
 
 ## Contributing
 

data/Rakefile

@@ -0,0 +1,10 @@
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.warning = false
+end
+
+task default: :test

data/altcha-rails.gemspec

@@ -1,16 +1,26 @@
 # frozen_string_literal: true
 
 Gem::Specification.new do |s|
-  s.name = "altcha-rails"
-  s.version = "0.0.5"
-  s.authors = ["Daniel Mack"]
-  s.homepage = "https://github.com/zonque/altcha-rails"
-  s.metadata = { "source_code_uri" => "https://github.com/zonque/altcha-rails" }
-  s.summary = "Rails helpers for ALTCHA"
-  s.description = "ALTCHA is a free, open-source CAPTCHA alternative that protects your website from spam and abuse"
-  s.email = "altcha-rails.gem@zonque.org"
+  s.name        = "altcha-rails"
+  s.version     = "0.1.0"
+  s.authors     = ["Daniel Mack"]
+  s.email       = "altcha-rails.gem@zonque.org"
+  s.homepage    = "https://github.com/zonque/altcha-rails"
+  s.metadata    = { "source_code_uri" => "https://github.com/zonque/altcha-rails" }
+  s.summary     = "Ruby library for ALTCHA"
+  s.description = "ALTCHA is a free, open-source CAPTCHA alternative that protects your website from spam and abuse. This gem implements the ALTCHA v1 challenge protocol (challenge creation and submission verification) and integrates with Rails.cache for replay protection."
+  s.licenses    = ["MIT"]
+
+  s.required_ruby_version = ">= 3.0"
+
   s.require_paths = ["lib"]
   s.files = `git ls-files`.split("\n")
-  s.licenses = ["MIT"]
+
+  # base64 is no longer a default gem as of Ruby 3.4.
+  s.add_runtime_dependency "base64", "~> 0.2"
+
+  s.add_development_dependency "minitest", "~> 5.0"
+  s.add_development_dependency "rake", "~> 13.0"
+
   s.specification_version = 4
 end

data/lib/altcha-rails.rb

@@ -1,65 +1,156 @@
 # frozen_string_literal: true
 
-module Altcha
-  mattr_accessor :configured
-  @@configured = false
-
-  mattr_accessor :algorithm
-  @@algorithm = 'SHA-256'
+require "base64"
+require "digest"
+require "json"
+require "openssl"
+require "securerandom"
 
-  mattr_accessor :num_range
-  @@num_range = (50_000..500_000)
+module Altcha
+  class ConfigurationError < StandardError; end
 
-  mattr_accessor :hmac_key
-  @@hmac_key = "change-me"
+  class << self
+    attr_accessor :algorithm, :max_number, :hmac_key, :timeout, :cache_key_prefix
+  end
 
-  mattr_accessor :timeout
-  @@timeout = 5.minutes
+  self.algorithm        = "SHA-256"
+  self.max_number       = 1_000_000
+  self.hmac_key         = nil
+  self.timeout          = 300 # seconds; accepts anything responding to #to_i
+  self.cache_key_prefix = "altcha:solution:"
 
   def self.setup
-    @@configured = true
     yield self
   end
 
-  class Challenge
-    attr_accessor :algorithm, :challenge, :salt, :signature
+  # Returns an Altcha::Challenge. Its #to_json produces the payload the
+  # widget expects via the `challenge` attribute.
+  def self.create_challenge(**options)
+    Challenge.create(**options)
+  end
 
-    def self.create
-      raise "Altcha not configured" unless Altcha.configured
+  # Verifies a base64-encoded JSON submission AND records it in Rails.cache
+  # for replay protection (atomic via `unless_exist: true`, TTL = timeout).
+  # Returns the Altcha::Submission on a fresh accept, nil on failure (invalid
+  # crypto, expired, spliced, or replay within the timeout window).
+  def self.verify(base64_string)
+    submission = Submission.verify(base64_string)
+    return nil unless submission
+
+    if Rails.cache.write("#{cache_key_prefix}#{submission.signature}", true,
+                         expires_in: timeout, unless_exist: true)
+      submission
+    else
+      nil # replay
+    end
+  end
 
-      secret_number = rand(Altcha.num_range)
+  class Challenge
+    attr_accessor :algorithm, :challenge, :salt, :signature, :max_number
+
+    def self.create(algorithm: nil, hmac_key: nil, max_number: nil, expires: nil, number: nil)
+      hmac_key ||= Altcha.hmac_key
+      raise ConfigurationError, "Altcha.hmac_key is not set" if hmac_key.nil? || hmac_key.empty?
+
+      algorithm  ||= Altcha.algorithm
+      max_number ||= Altcha.max_number
+      expires    ||= Time.now.to_i + Altcha.timeout.to_i
+      number     ||= SecureRandom.random_number(max_number)
+
+      ch = new
+      ch.algorithm  = algorithm
+      ch.max_number = max_number
+      # Canonical v1 ALTCHA salt: random hex, expires parameter, trailing '&'
+      # to delimit the parameter list from the nonce (CVE-2025-68113).
+      ch.salt       = "#{SecureRandom.hex(12)}?expires=#{expires.to_i}&"
+      ch.challenge  = Digest::SHA256.hexdigest(ch.salt + number.to_s)
+      ch.signature  = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new(algorithm), hmac_key, ch.challenge)
+      ch
+    end
 
-      a = Challenge.new
-      a.algorithm = Altcha.algorithm
-      a.salt = [Time.now.to_s, SecureRandom.hex(12)].join('|')
-      a.challenge = Digest::SHA256.hexdigest(a.salt + secret_number.to_s)
-      a.signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new(a.algorithm), Altcha.hmac_key, a.challenge)
+    def to_h
+      {
+        algorithm: algorithm,
+        challenge: challenge,
+        maxnumber: max_number,
+        salt: salt,
+        signature: signature,
+      }
+    end
 
-      return a
+    def to_json(*args)
+      to_h.to_json(*args)
     end
   end
 
   class Submission
-    attr_accessor :algorithm, :challenge, :salt, :signature, :number
-
-    def initialize(v = {})
-      @algorithm = v["algorithm"] || ""
-      @challenge = v["challenge"] || ""
-      @signature = v["signature"] || ""
-      @salt      = v["salt"]      || ""
-      @number    = v["number"]    || 0
+    attr_reader :algorithm, :challenge, :salt, :signature, :number
+
+    def self.verify(base64_string)
+      raw = begin
+        Base64.decode64(base64_string.to_s)
+      rescue ArgumentError
+        return nil
+      end
+      payload = JSON.parse(raw) rescue nil
+      return nil unless payload.is_a?(Hash)
+
+      submission = new(payload)
+      submission.valid? ? submission : nil
+    end
+
+    def initialize(payload = {})
+      @algorithm = payload["algorithm"].to_s
+      @challenge = payload["challenge"].to_s
+      @signature = payload["signature"].to_s
+      @salt      = payload["salt"].to_s
+      @number    = payload["number"]
     end
 
     def valid?
-      check = Digest::SHA256.hexdigest(@salt + @number.to_s)
+      return false unless @algorithm == Altcha.algorithm
+      return false unless @number.is_a?(Integer)
+      return false if Altcha.hmac_key.nil? || Altcha.hmac_key.empty?
+
+      expires = extract_expires(@salt)
+      return false if expires.nil?
+      return false unless Time.at(expires) > Time.now
+
+      # Normalize to canonical trailing-'&' form before recomputing the hash;
+      # a spliced salt no longer round-trips to the same digest. Mitigates
+      # CVE-2025-68113.
+      canonical_salt = @salt.end_with?("&") ? @salt : "#{@salt}&"
+      check = Digest::SHA256.hexdigest(canonical_salt + @number.to_s)
+
+      return false unless @challenge == check
+
+      expected_sig = OpenSSL::HMAC.hexdigest(
+        OpenSSL::Digest.new(@algorithm), Altcha.hmac_key, check
+      )
+      secure_compare(@signature, expected_sig)
+    end
+
+    private
+
+    def extract_expires(salt)
+      query = salt.split("?", 2)[1]
+      return nil unless query
+
+      query.split("&").each do |pair|
+        key, value = pair.split("=", 2)
+        return Integer(value, 10) if key == "expires" && value
+      end
+      nil
+    rescue ArgumentError
+      nil
+    end
 
-      parts = @salt.split('|')
-      t = Time.parse(parts[0]) rescue nil
+    def secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
 
-      return @algorithm == Altcha.algorithm &&
-        @challenge == check &&
-        @signature == OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new(Altcha.algorithm), Altcha.hmac_key, check) &&
-        t.present? && t > Time.now - Altcha.timeout && t < Time.now
+      diff = 0
+      a.bytes.zip(b.bytes) { |x, y| diff |= x ^ y }
+      diff.zero?
     end
   end
 end

data/test/altcha_test.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class AltchaTest < Minitest::Test
+  HMAC_KEY = "test-secret-key"
+
+  def setup
+    @prev_hmac_key   = Altcha.hmac_key
+    @prev_timeout    = Altcha.timeout
+    @prev_max_number = Altcha.max_number
+    @prev_algorithm  = Altcha.algorithm
+    @prev_prefix     = Altcha.cache_key_prefix
+
+    Altcha.hmac_key         = HMAC_KEY
+    Altcha.timeout          = 300
+    Altcha.max_number       = 1_000
+    Altcha.algorithm        = "SHA-256"
+    Altcha.cache_key_prefix = "altcha:solution:"
+
+    Rails.cache.clear
+  end
+
+  def teardown
+    Altcha.hmac_key         = @prev_hmac_key
+    Altcha.timeout          = @prev_timeout
+    Altcha.max_number       = @prev_max_number
+    Altcha.algorithm        = @prev_algorithm
+    Altcha.cache_key_prefix = @prev_prefix
+  end
+
+  # -- helpers --------------------------------------------------------------
+
+  def encode(hash)
+    Base64.strict_encode64(hash.to_json)
+  end
+
+  def solve(challenge)
+    (0..Altcha.max_number).find do |n|
+      Digest::SHA256.hexdigest(challenge.salt + n.to_s) == challenge.challenge
+    end
+  end
+
+  def payload_for(challenge, number)
+    {
+      "algorithm" => challenge.algorithm,
+      "challenge" => challenge.challenge,
+      "number"    => number,
+      "salt"      => challenge.salt,
+      "signature" => challenge.signature,
+    }
+  end
+
+  def solved_payload
+    ch = Altcha.create_challenge
+    [ch, encode(payload_for(ch, solve(ch)))]
+  end
+
+  # -- Altcha.create_challenge ---------------------------------------------
+
+  def test_create_challenge_returns_challenge_with_required_fields
+    ch = Altcha.create_challenge
+    assert_equal "SHA-256", ch.algorithm
+    assert_equal 1_000, ch.max_number
+    refute_nil ch.salt
+    refute_nil ch.challenge
+    refute_nil ch.signature
+  end
+
+  def test_create_challenge_salt_uses_canonical_v1_format
+    ch = Altcha.create_challenge
+    assert_match(/\A[0-9a-f]{24}\?expires=\d+&\z/, ch.salt,
+                 "salt must be `<hex>?expires=<unix>&` (CVE-2025-68113 mitigation)")
+  end
+
+  def test_create_challenge_signature_is_hmac_of_challenge_with_configured_key
+    ch = Altcha.create_challenge
+    expected = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("SHA-256"), HMAC_KEY, ch.challenge)
+    assert_equal expected, ch.signature
+  end
+
+  def test_create_challenge_challenge_field_is_sha256_of_salt_plus_secret
+    ch = Altcha.create_challenge
+    n = solve(ch)
+    refute_nil n, "solver could not find secret within max_number"
+    assert_equal ch.challenge, Digest::SHA256.hexdigest(ch.salt + n.to_s)
+  end
+
+  def test_create_challenge_to_json_emits_widget_compatible_payload
+    json = JSON.parse(Altcha.create_challenge.to_json)
+    assert_equal %w[algorithm challenge maxnumber salt signature], json.keys.sort
+    assert_equal "SHA-256", json["algorithm"]
+    assert_equal 1_000, json["maxnumber"]
+  end
+
+  def test_create_challenge_raises_when_hmac_key_is_nil
+    Altcha.hmac_key = nil
+    assert_raises(Altcha::ConfigurationError) { Altcha.create_challenge }
+  end
+
+  def test_create_challenge_raises_when_hmac_key_is_empty
+    Altcha.hmac_key = ""
+    assert_raises(Altcha::ConfigurationError) { Altcha.create_challenge }
+  end
+
+  def test_create_challenge_accepts_per_call_overrides
+    explicit_expires = Time.now.to_i + 9999
+    ch = Altcha.create_challenge(expires: explicit_expires, number: 42, max_number: 100)
+    assert_match(/\?expires=#{explicit_expires}&\z/, ch.salt)
+    assert_equal 100, ch.max_number
+    assert_equal ch.challenge, Digest::SHA256.hexdigest(ch.salt + "42")
+  end
+
+  # -- Altcha.verify: happy path -------------------------------------------
+
+  def test_verify_accepts_a_valid_fresh_submission
+    ch, b64 = solved_payload
+    submission = Altcha.verify(b64)
+    refute_nil submission
+    assert_kind_of Altcha::Submission, submission
+    assert_equal ch.signature, submission.signature
+  end
+
+  # -- Altcha.verify: replay protection ------------------------------------
+
+  def test_verify_rejects_a_replay_of_the_same_submission
+    _ch, b64 = solved_payload
+    refute_nil Altcha.verify(b64), "first submission must be accepted"
+    assert_nil Altcha.verify(b64), "replay must be rejected"
+  end
+
+  def test_verify_writes_to_cache_under_the_signature_keyed_prefix
+    ch, b64 = solved_payload
+    Altcha.verify(b64)
+    assert_equal true, Rails.cache.read("altcha:solution:#{ch.signature}")
+  end
+
+  def test_verify_honours_configured_cache_key_prefix
+    Altcha.cache_key_prefix = "myapp:altcha:"
+    ch, b64 = solved_payload
+    Altcha.verify(b64)
+    assert_equal true, Rails.cache.read("myapp:altcha:#{ch.signature}")
+    assert_nil Rails.cache.read("altcha:solution:#{ch.signature}")
+  end
+
+  def test_verify_passes_timeout_through_as_expires_in
+    Altcha.timeout = 42
+    ch, b64 = solved_payload
+    Altcha.verify(b64)
+    entry = Rails.cache.entry("altcha:solution:#{ch.signature}")
+    assert_equal 42, entry[:expires_in]
+  end
+
+  def test_verify_does_not_touch_cache_when_crypto_check_fails
+    bad = "not-a-real-payload"
+    Altcha.verify(bad)
+    assert_empty Rails.cache.keys
+  end
+
+  # -- Altcha.verify: failure modes (crypto) -------------------------------
+
+  def test_verify_returns_nil_on_garbage_input
+    assert_nil Altcha.verify("garbage!!!!")
+    assert_nil Altcha.verify("")
+    assert_nil Altcha.verify(nil)
+  end
+
+  def test_verify_returns_nil_when_payload_is_not_a_hash
+    assert_nil Altcha.verify(Base64.strict_encode64('"a string"'))
+    assert_nil Altcha.verify(Base64.strict_encode64("123"))
+    assert_nil Altcha.verify(Base64.strict_encode64("[]"))
+  end
+
+  def test_verify_rejects_wrong_algorithm
+    ch = Altcha.create_challenge
+    n = solve(ch)
+    p = payload_for(ch, n).merge("algorithm" => "SHA-512")
+    assert_nil Altcha.verify(encode(p))
+  end
+
+  def test_verify_rejects_non_integer_number
+    ch = Altcha.create_challenge
+    n = solve(ch)
+    p = payload_for(ch, n).merge("number" => n.to_s)
+    assert_nil Altcha.verify(encode(p))
+  end
+
+  def test_verify_rejects_tampered_number
+    ch = Altcha.create_challenge
+    n = solve(ch)
+    p = payload_for(ch, n + 1)
+    assert_nil Altcha.verify(encode(p))
+  end
+
+  def test_verify_rejects_tampered_challenge
+    ch = Altcha.create_challenge
+    n = solve(ch)
+    p = payload_for(ch, n).merge("challenge" => "0" * ch.challenge.length)
+    assert_nil Altcha.verify(encode(p))
+  end
+
+  def test_verify_rejects_tampered_signature
+    ch = Altcha.create_challenge
+    n = solve(ch)
+    p = payload_for(ch, n).merge("signature" => "0" * ch.signature.length)
+    assert_nil Altcha.verify(encode(p))
+  end
+
+  def test_verify_rejects_expired_challenge
+    Altcha.timeout = -1
+    ch = Altcha.create_challenge
+    Altcha.timeout = 300
+    n = solve(ch)
+    assert_nil Altcha.verify(encode(payload_for(ch, n)))
+  end
+
+  def test_verify_rejects_salt_without_expires_parameter
+    salt = "#{SecureRandom.hex(12)}&"
+    challenge = Digest::SHA256.hexdigest(salt + "42")
+    signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("SHA-256"), HMAC_KEY, challenge)
+    p = {
+      "algorithm" => "SHA-256",
+      "challenge" => challenge,
+      "number"    => 42,
+      "salt"      => salt,
+      "signature" => signature,
+    }
+    assert_nil Altcha.verify(encode(p))
+  end
+
+  def test_verify_rejects_when_hmac_key_not_configured
+    _ch, b64 = solved_payload
+    Altcha.hmac_key = nil
+    assert_nil Altcha.verify(b64)
+  end
+
+  # -- CVE-2025-68113 regression -------------------------------------------
+
+  def test_verify_rejects_parameter_splice_attack
+    # Construct a hash-colliding splice. Without the trailing-'&' normalisation
+    # in valid?, this submission would be accepted:
+    #   SHA256(salt + "1" + "23") == SHA256(salt + "123")
+    salt = "abc123def456abc123def456?expires=#{Time.now.to_i + 60}&"
+    legitimate_hash = Digest::SHA256.hexdigest(salt + "123")
+    signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("SHA-256"), HMAC_KEY, legitimate_hash)
+
+    # Sanity: prove the collision exists before testing rejection.
+    assert_equal legitimate_hash, Digest::SHA256.hexdigest((salt + "1") + "23"),
+                 "splice precondition: hash collision must exist for this test to be meaningful"
+
+    spliced = {
+      "algorithm" => "SHA-256",
+      "challenge" => legitimate_hash,
+      "number"    => 23,
+      "salt"      => salt + "1",
+      "signature" => signature,
+    }
+    assert_nil Altcha.verify(encode(spliced)),
+               "CVE-2025-68113: spliced submission must be rejected"
+  end
+
+  # -- Altcha.setup --------------------------------------------------------
+
+  def test_setup_yields_the_module
+    yielded = nil
+    Altcha.setup { |c| yielded = c }
+    assert_same Altcha, yielded
+  end
+
+  def test_setup_assignments_persist
+    Altcha.setup do |c|
+      c.max_number = 7777
+      c.timeout = 60
+    end
+    assert_equal 7777, Altcha.max_number
+    assert_equal 60, Altcha.timeout
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+# Stub Rails.cache so the gem's replay-tracking path can run without booting
+# Rails. The fake mimics the subset of ActiveSupport::Cache::Store that the
+# gem uses: write(key, value, expires_in:, unless_exist:).
+class FakeCache
+  def initialize
+    @store = {}
+  end
+
+  def write(key, value, expires_in:, unless_exist: false)
+    return false if unless_exist && @store.key?(key)
+
+    @store[key] = { value: value, expires_in: expires_in }
+    true
+  end
+
+  def read(key)
+    entry = @store[key]
+    entry && entry[:value]
+  end
+
+  def clear
+    @store.clear
+  end
+
+  def keys
+    @store.keys
+  end
+
+  def entry(key)
+    @store[key]
+  end
+end
+
+module Rails
+  class << self
+    attr_accessor :cache
+  end
+  self.cache = FakeCache.new
+end
+
+require "altcha-rails"
+require "minitest/autorun"

metadata

@@ -1,17 +1,60 @@
 --- !ruby/object:Gem::Specification
 name: altcha-rails
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.1.0
 platform: ruby
 authors:
 - Daniel Mack
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-02-11 00:00:00.000000000 Z
-dependencies: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
 description: ALTCHA is a free, open-source CAPTCHA alternative that protects your
-  website from spam and abuse
+  website from spam and abuse. This gem implements the ALTCHA v1 challenge protocol
+  (challenge creation and submission verification) and integrates with Rails.cache
+  for replay protection.
 email: altcha-rails.gem@zonque.org
 executables: []
 extensions: []
@@ -19,21 +62,19 @@ extra_rdoc_files: []
 files:
 - ".editorconfig"
 - ".gitignore"
+- Gemfile
 - LICENSE
 - README.md
+- Rakefile
 - altcha-rails.gemspec
 - lib/altcha-rails.rb
-- lib/generators/altcha/install/install_generator.rb
-- lib/generators/altcha/install/templates/controllers/altcha_controller.rb
-- lib/generators/altcha/install/templates/initializers/altcha.rb
-- lib/generators/altcha/install/templates/migrations/create_altcha_solutions.rb.erb
-- lib/generators/altcha/install/templates/models/altcha_solution.rb
+- test/altcha_test.rb
+- test/test_helper.rb
 homepage: https://github.com/zonque/altcha-rails
 licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/zonque/altcha-rails
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -41,15 +82,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 4.0.6
 specification_version: 4
-summary: Rails helpers for ALTCHA
+summary: Ruby library for ALTCHA
 test_files: []

data/lib/generators/altcha/install/install_generator.rb

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-require "rails/generators/active_record"
-
-module Altcha
-  module Generators
-    class InstallGenerator < ActiveRecord::Generators::Base
-      desc "Installs Altcha for Rails and generates a model, a controller and a route"
-      argument :name, type: :string, default: "Altcha"
-
-      source_root File.expand_path("templates", __dir__)
-
-      def create_model
-        copy_file "models/altcha_solution.rb", "app/models/altcha_solution.rb"
-      end
-
-      def create_controller
-        copy_file "controllers/altcha_controller.rb", "app/controllers/altcha_controller.rb"
-      end
-
-      def create_initializer
-        copy_file "initializers/altcha.rb", "config/initializers/altcha.rb"
-      end
-
-      def setup_routes
-        route  "get '/altcha', to: 'altcha#new'"
-      end
-
-      def create_migrations
-        migration_template "migrations/create_altcha_solutions.rb.erb", "db/migrate/create_altcha_solutions.rb"
-      end
-    end
-  end
-end

data/lib/generators/altcha/install/templates/controllers/altcha_controller.rb

@@ -1,5 +0,0 @@
-class AltchaController < ApplicationController
-  def new
-    render json: Altcha::Challenge.create.to_json
-  end
-end

data/lib/generators/altcha/install/templates/initializers/altcha.rb

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-Altcha.setup do |config|
-  config.algorithm = 'SHA-256'
-  config.num_range = (50_000..500_000)
-  config.timeout = 5.minutes
-  config.hmac_key = 'change-me'
-end

data/lib/generators/altcha/install/templates/migrations/create_altcha_solutions.rb.erb

@@ -1,15 +0,0 @@
-class CreateAltchaSolutions < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version.to_s %>]
-  def change
-    create_table(:altcha_solutions) do |t|
-      t.string :algorithm
-      t.string :challenge
-      t.string :salt
-      t.string :signature
-      t.integer :number
-
-      t.timestamps
-    end
-
-    add_index :altcha_solutions, [ :algorithm, :challenge, :salt, :signature, :number ], unique: true
-  end
-end

data/lib/generators/altcha/install/templates/models/altcha_solution.rb

@@ -1,28 +0,0 @@
-class AltchaSolution < ApplicationRecord
-  validates :algorithm, :challenge, :salt, :signature, :number, presence: true
-  attr_accessor :took
-
-  def self.verify_and_save(base64encoded)
-    p = JSON.parse(Base64.decode64(base64encoded)) rescue nil
-    return false if p.nil?
-
-    submission = Altcha::Submission.new(p)
-    return false unless submission.valid?
-
-    solution = self.new(p)
-
-    begin
-      return solution.save
-    rescue ActiveRecord::RecordNotUnique
-      # Replay attack
-      return false
-    end
-  end
-
-  def self.cleanup
-    # Replay attacks are protected by the time stamp in the salt of the challenge for
-    # the duration configured in the timeout. All solutions in the database that older
-    # can be deleted.
-    AltchaSolution.where('created_at < ?', Time.now - Altcha.timeout).delete_all
-  end
-end