active_hashcash 0.3.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27a33816eb2072dd2a76ed1f2844b1cd2f38915913f54a7ba4f855c5244ba1af
-  data.tar.gz: d9e0ad4861a95a9140d68005186ffa15ea369da874c3753c9230fefae260d870
+  metadata.gz: ef5393e959b8a94792f35bc043c87542568398d3c9444a8e238ba6eafdbb3522
+  data.tar.gz: 74a51e94325581bf35113f81ccaccd696079bc43cfedc7f734ae5889ab0bb32f
 SHA512:
-  metadata.gz: 22a0e700d62551411c188dc33062b6b7738f08cc6da250c779beef08db7c3d98ea987c2cffebdfd9fe83c9879da293b570124cc86508fd19a32e7743bf7e50f3
-  data.tar.gz: ddf4aa8b020df59032e7f0711228279ecf375e903b46ce6a748c1b17d408277328db00f19b89955be639faaae7886e1ed700d2185fc91b520a547e0507afd3c4
+  metadata.gz: 5d0da77fac447177abebbf04a585927f42d7a100159bf9ab8df1305f1f88b9a394738c03f5a828177dea71f745a941b9bff7a8625c4cc8c5744fc735ef017cc2
+  data.tar.gz: 6845cb211b39fa5dfe0f0393df05ae7cd6e5b54f5e8f3e27e26a206f9853b026a7a557e0c5dbbf97e2eb1bc5468b4ef418cec31a9e20c98153b8027c13d30947

data/CHANGELOG.md

@@ -1,8 +1,22 @@
 # Changelog of ActiveHashcash
 
+## 0.5.0 (2026-08-08)
+
+- Fix stamp date mismatch by using server date instead of client
+- Replace SHA-1 with SHA-256 for proof-of-work stamps
+- Mine stamps in a Web Worker using pure JS SHA-256 (keeps the main thread unblocked)
+- Support SHA-1 fallback on the backend for backward compatibility (via the `ext` stamp field)
+
+## 0.4.0 (2025-05-15)
+
+- Prevent from password managers to submit the form before the stamp has been computed
+- Added support for the "button" submit form tag
+- Added Catalan language
+- Added `base_controller_class` configuration option to allow specifying a custom base controller for the ActiveHashcash dashboard, enhancing flexibility in diverse application architectures.
+
 ## 0.3.2 (2024-08-29)
 
-- Fix methods conflitc by not including ActionView::Helpers::FormTagHelper
+- Fix methods conflict by not including ActionView::Helpers::FormTagHelper
 - Sanitize params by forcing as a String
 
 ## 0.3.1 - 2024-04-04

data/README.md

@@ -1,14 +1,14 @@
 # ActiveHashcash
 
-<img align="right" width="200px" src="logo.png" alt="Active Hashcash logo"/>
+Protect Rails applications against bots and brute force attacks without annoying humans.
 
-ActiveHashcash protects Rails applications against bots and brute force attacks without annoying humans.
+<div><img align="right" width="200px" src="logo.png" alt="Active Hashcash logo"/></div>
 
 Hashcash is proof-of-work algorithm, invented by Adam Back in 1997, to protect systems against denial of service attacks.
 ActiveHashcash is an easy way to protect any Rails application against brute force attacks and bots.
 
 The idea is to force clients to spend some time to solve a hard problem that is very easy to verify for the server.
-We have developped ActiveHashcash after seeing brute force attacks against our Rails application monitoring service [RorVsWild](https://rorvswild.com).
+We have developed ActiveHashcash after seeing brute force attacks against our Rails application monitoring service [RorVsWild](https://rorvswild.com).
 
 ActiveHashcash is ideal to set up on sensitive forms such as login and registration.
 While the user is filling the form, the problem is solved in JavaScript and set the result into a hidden input text.
@@ -27,37 +27,40 @@ Here is a [demo on a registration form](https://www.rorvswild.com/session) :
 
 ---
 
-<img align="left" height="24px" src="rorvswild_logo.jpg" alt="RorVsWild logo"/>Made by <a href="https://www.rorvswild.com">RorVsWild</a>, performances & exceptions monitoring for Ruby on Rails applications.
+<div><img align="left" height="24px" src="rorvswild_logo.jpg" alt="RorVsWild logo"/>Made by <a href="https://www.rorvswild.com">RorVsWild</a>, performances & exceptions monitoring for Ruby on Rails applications.</div>
 
 ---
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add this line to your application's Gemfile and run `bundle install`:
 
 ```ruby
 gem "active_hashcash"
 ```
 
-Require hashcash from your JavaScript manifest.
+Stamps are stored into the database to prevents from spending them more than once.
+You must install and run a migration:
 
-```js
-//= require hashcash
+```
+rails active_hashcash:install:migrations
+rails db:migrate
 ```
 
-OR
-
-Link hashcash to your JavaScript manifest and load it to your head.
+Then you have to include ActiveHashcash and add a `before_action :check_hashcash` in you controller:
 
-```js
-//= link hashcash.js
-```
+```ruby
+class SessionController < ApplicationController
+  include ActiveHashcash
 
-```erb
-<%= javascript_include_tag "hashcash", "data-turbo-track": "reload", defer: true %>
+  # Only the action receiving the form needs to be protected
+  before_action :check_hashcash, only: :create
+end
 ```
 
-Add a Hashcash hidden field into the form you want to protect.
+The action `SessionController#create` is now protected.
+The final step is compute the hashcash from the client side.
+Start by adding a Hashcash hidden field into the form you want to protect.
 
 ```erb
 <form>
@@ -65,28 +68,28 @@ Add a Hashcash hidden field into the form you want to protect.
 </form>
 ```
 
-Then you have to define a `before_action :check_hashcash` in you controller.
-
-```ruby
-class SessionController < ApplicationController
-  include ActiveHashcash
+Require hashcash from your JavaScript manifest.
 
-  # Only the action receiving the form needs to be protected
-  before_action :check_hashcash, only: :create
-end
+```js
+//= require hashcash
 ```
 
-To customize some behaviour, you can override most of the methods which begins with `hashcash_`.
-Simply have a look to `active_hashcash.rb`.
-
-Stamps are stored into into the database to prevents from spending them more than once.
-You must run a migration:
+Or, link hashcash to your JavaScript manifest and load it to your head.
 
+```js
+//= link hashcash.js
 ```
-rails active_hashcash:install:migrations
-rails db:migrate
+
+```erb
+<%= javascript_include_tag "hashcash", "data-turbo-track": "reload", defer: true %>
 ```
 
+The hashcash stamp will be set in the hidden input once computed and the submit button enabled.
+
+To customize behaviours, you can override methods of ActiveHashcash module.
+
+
+
 ### Dashboard
 
 There is a mountable dashboard which allows to see all spent stamps.
@@ -99,10 +102,22 @@ It's not mandatory, but useful for monitoring purpose.
 mount ActiveHashcash::Engine, at: "hashcash"
 ```
 
-ActiveHashcash cannot guess how you handle user authentication, because it is different for all Rails applications.
-So you have to monkey patch `ActiveHashcash::ApplicationController` in order to inject your own mechanism.
-The patch can be saved wherever you want.
-For example, I like to have all the patches in one place, so I put them in `lib/patches`.
+ActiveHashcash cannot guess how user authentication is handled, because it is different for all Rails applications.
+So here is 3 options.
+
+#### Inheritance
+
+By default ActiveHashcash extends `ActionController::Base`, but you can change it to any controller, such as `AdminController`.
+
+```ruby
+# config/initializers/active_hashcash.rb
+Rails.application.configure do
+  ActiveHashcash.base_controller_class = "AdminController"
+end
+```
+#### Monkey patching
+
+Monkey patching `ActiveHashcash::ApplicationController` let you inject your own mechanism.
 
 ```ruby
 # lib/patches/active_hashcash.rb
@@ -118,9 +133,7 @@ ActiveHashcash::ApplicationController.class_eval do
 end
 ```
 
-Then you have to require the monkey patch.
-Because it's loaded via require, it won't be reloaded in development.
-Since you are not supposed to change this file often, it should not be an issue.
+Then the patch has to be loaded from after initialization:
 
 ```ruby
 # config/application.rb
@@ -129,7 +142,9 @@ config.after_initialize do
 end
 ```
 
-If you use Devise, you can check the permission directly from routes.rb:
+#### With Devise
+
+Permission check can be achieved directly from routes.rb:
 
 ```ruby
 # config/routes.rb
@@ -141,7 +156,7 @@ end
 ### Before version 0.3.0
 
 You must have Redis in order to prevent double spent stamps. Otherwise it will be useless.
-It automatically tries to connect with the environement variables `ACTIVE_HASHCASH_REDIS_URL` or `REDIS_URL`.
+It automatically tries to connect with the environment variables `ACTIVE_HASHCASH_REDIS_URL` or `REDIS_URL`.
 You can also manually set the URL with `ActiveHashcash.redis_url = redis://user:password@localhost:6379`.
 
 You should call `ActiveHashcash::Store#clean` once a day, to remove expired stamps.
@@ -157,23 +172,35 @@ rails db:migrate
 
 Complexity is the most important parameter. By default its value is 20 and requires most of the time 5 to 20 seconds to be solved on a decent laptop.
 The user won't wait that long, since he needs to fill the form while the problem is solving.
-Howevever, if your application includes people with slow and old devices, then consider lowering this value, to 16 or 18.
+However, if your application includes people with slow and old devices, then consider lowering this value, to 16 or 18.
 
 You can change the minimum complexity with `ActiveHashcash.bits = 20`.
 
 Since version 0.3.0, the complexity increases with the number of stamps spent during le last 24H from the same IP address.
 Thus it becomes very efficient to slow down brute force attacks.
 
+## Testing
+
+Browser tests submit the real form, so they have to compute a real stamp. At the default 16 bits this adds noticeable time to every submission and slows down your suite. Drop the complexity in the test environment so it finishes almost instantly:
+
+```ruby
+# spec/rails_helper.rb (RSpec) or test/test_helper.rb (Minitest)
+ActiveHashcash.bits = 2
+```
+
+In controller tests, provide the hashcash this way:
+
+```ruby
+post(url, params: {hashcash: ActiveHashcash::Stamp.mint(host).to_s})
+```
+
 ## Limitations
 
-The JavaScript implementation is 10 to 20 times slower than the official C version.
-I first used the SubtleCrypto API but it is surprisingly slower than a custom SHA1 implementation.
-Maybe I did in an unefficient way 2df3ba5?
-Another idea would be to compile the work algorithm in wasm.
+The JavaScript implementation is slower than the official C version.
+It uses a pure JS SHA-256 implementation running inside a Web Worker, which keeps the main thread responsive while mining.
+A synchronous tight loop avoids the per-call async overhead of `crypto.subtle.digest()`, making it the fastest browser-side approach across Chrome and Safari.
 
-Unfortunately, I'm not a JavaScript expert.
-Maybe you have good JS skills to optimize it?
-Any help would be appreciate to better fights bots and brute for attacks!
+No `crypto.subtle` or secure context (HTTPS) is required, so it works in any environment including plain HTTP during development.
 
 ## Contributing
 
@@ -183,4 +210,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/BaseSe
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-Made by Alexis Bernard at [RorVsWild](https://www.rorvswild.com).
+Made by [Alexis Bernard](https://alexis.bernard.io/).