altcha-rails 0.0.4 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85c137a5cb28c3aba10baa2fb0a9726c357273b3fa3e18803c0b062fe1e899b8
-  data.tar.gz: 935c3e5086bd1ce0e0903daf71cbbef552e36d5d457853fd56410b63a4e2a991
+  metadata.gz: 166ab2cdd6732e309f96c332d0483bcb16f984697f6f56ffab78357635aaccc3
+  data.tar.gz: baa9cf000ae61e2a1da2e3571827ff318d046ca3707e0341c6a6c036718b9278
 SHA512:
-  metadata.gz: 34d5185abba605464ef98015180cef4f74c670433cb6ee28070e2b7780b32c738fc065201a66edbcd58c333a8c6cee9b03b7dc3b914bd259e00efa885a07afdd
-  data.tar.gz: 6198c9f114b1a5a8c8ac02a4171d4d79fdcc18cf1c6c073f753e07f773788e2b99c5390f6e5505119cdcc2034132b63609cee6724c0a83e3951dfe414d07a75f
+  metadata.gz: 554a2a258ad6e498034ae21d82788ca50b93543fcdfe086cc346b270c8ebc35a7c44702a30bf3ca0d618ac3b38c0943f04099b47a34c37ad33c8f5a2e1555b11
+  data.tar.gz: 9acd0d3bedda678efb8480d9d4935cdc1e1d8f97455eeba40e4dbb692e9753a5d9662ce0d05f841f98af2d2288aa6102267e93765d6873df2c12d59d1b4be0f2

data/.editorconfig

@@ -0,0 +1,5 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4

data/.gitignore

@@ -0,0 +1,2 @@
+/*.gem
+

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2024 Daniel Mack
+
+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,112 @@
+[![Gem Version](https://badge.fury.io/rb/altcha-rails.svg)](https://badge.fury.io/rb/altcha-rails)
+
+# Ruby gem for ALTCHA
+
+[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-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.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```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:
+
+```
+$ 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).
+
+You will also have to run 'rails db:migrate` to apply pending changes to the database.
+
+## Configuration
+
+The initializer file `config/initializers/altcha.rb` contains 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'
+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 random 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.
+
+## 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.
+
+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 purge outdates soltutions from the database.
+
+## Usage
+
+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.
+
+Then add the following code to the form you want to protect:
+
+```erb
+<altcha-widget challengeurl="<%= altcha_url() %>"></altcha-widget>
+```
+
+Once the user clicks the checkbox, the widget will send a request to the server to get a new challenge.
+When the user-side code inside the widget found the solution to the challenge, the spinner will stop
+and a hidden input field with the name `altcha` will be created in the form to convey the solution as
+base64 encoded JSON dictionary.
+
+In the controller that handles the form submission, you can verify the response with the following code:
+
+```ruby
+def create
+  @model = Model.create(model_params)
+
+  unless AltchaSolution.verify_and_save(params.permit(:altcha)[:altcha])
+    flash.now[:alert] = 'ALTCHA verification failed.'
+    render :new, status: :unprocessable_entity
+    return
+  end
+
+  # ...
+end
+```
+
+The `verify_and_save` method will return `true` if the response is valid and has not been used before.
+
+## Contributing
+
+Bug reports and pull requests are welcome.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/altcha-rails.gemspec

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |s|
+  s.name = "altcha-rails"
+  s.version = "0.0.6"
+  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.require_paths = ["lib"]
+  s.files = `git ls-files`.split("\n")
+  s.licenses = ["MIT"]
+  s.specification_version = 4
+end

data/lib/altcha-rails.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Altcha
+  mattr_accessor :configured
+  @@configured = false
+
+  mattr_accessor :algorithm
+  @@algorithm = 'SHA-256'
+
+  mattr_accessor :num_range
+  @@num_range = (50_000..500_000)
+
+  mattr_accessor :hmac_key
+  @@hmac_key = "change-me"
+
+  mattr_accessor :timeout
+  @@timeout = 5.minutes
+
+  def self.setup
+    @@configured = true
+    yield self
+  end
+
+  class Challenge
+    attr_accessor :algorithm, :challenge, :salt, :signature
+
+    def self.create
+      raise "Altcha not configured" unless Altcha.configured
+
+      secret_number = rand(Altcha.num_range)
+
+      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)
+
+      return a
+    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
+    end
+
+    def valid?
+      check = Digest::SHA256.hexdigest(@salt + @number.to_s)
+
+      parts = @salt.split('|')
+      t = Time.parse(parts[0]) rescue nil
+
+      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
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# 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

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

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

@@ -0,0 +1,8 @@
+# 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

@@ -0,0 +1,15 @@
+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, name: 'index_altcha_solutions'
+  end
+end

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

@@ -0,0 +1,28 @@
+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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: altcha-rails
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.6
 platform: ruby
 authors:
 - Daniel Mack
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-02-11 00:00:00.000000000 Z
+date: 2024-04-28 00:00:00.000000000 Z
 dependencies: []
 description: ALTCHA is a free, open-source CAPTCHA alternative that protects your
   website from spam and abuse
@@ -16,7 +16,18 @@ email: altcha-rails.gem@zonque.org
 executables: []
 extensions: []
 extra_rdoc_files: []
-files: []
+files:
+- ".editorconfig"
+- ".gitignore"
+- LICENSE
+- README.md
+- 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
 homepage: https://github.com/zonque/altcha-rails
 licenses:
 - MIT