active_hashcash 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef5393e959b8a94792f35bc043c87542568398d3c9444a8e238ba6eafdbb3522
-  data.tar.gz: 74a51e94325581bf35113f81ccaccd696079bc43cfedc7f734ae5889ab0bb32f
+  metadata.gz: 0c53df9a89fac1a14b89fb109520d7b2c35d1455b3b2624d9200186d9a295cf7
+  data.tar.gz: d090c36da4d4d17f80b5d7a653cbe2544fc311cdcf63a97bd3b46d1cf944631b
 SHA512:
-  metadata.gz: 5d0da77fac447177abebbf04a585927f42d7a100159bf9ab8df1305f1f88b9a394738c03f5a828177dea71f745a941b9bff7a8625c4cc8c5744fc735ef017cc2
-  data.tar.gz: 6845cb211b39fa5dfe0f0393df05ae7cd6e5b54f5e8f3e27e26a206f9853b026a7a557e0c5dbbf97e2eb1bc5468b4ef418cec31a9e20c98153b8027c13d30947
+  metadata.gz: cde7a3bfff3389e1761e461dad1a44a2fd480078fd5fb80362c59f5a4a8f8601feff6a9bf28785bab757abf725213060bffaa724815c8a131b3424f7145bedb5
+  data.tar.gz: 3f1c4d3842d4ef2aa871c986d36a9557c3c2b5f94145cdb65375dff56bf3a8e8bd5a24e718783962c3f4a5aaacfef709ae5c2f063b79794fec728ac3c9ef1aab

data/AGENTS.md

@@ -0,0 +1,9 @@
+# Agents - ActiveHashcas
+
+## Coding instructions
+
+- Keep everything as simple as possible
+- Do not extract methods in modules from your initiative
+- Do not use service objects
+- Do not rescue exceptions unless a specific behavior is required
+- Do not test private methods

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog of ActiveHashcash
 
+## 0.6.0 (2026-09-22)
+
+- Penalize bad IPs reported by FireHOL lists. For this feature to do anything you must run the migration and schedule the sync job from a cron:
+
+    ```
+    rails active_hashcash:install:migrations
+    rails db:migrate
+    ```
+
+    Then schedule `ActiveHashcash::Reputation::UpdateAllScoresJob.perform_later` anywhere from once per hour to once per day.
+
+- Add `ActiveHashcash.throttle_rules` to slow down pushy IPs
+
 ## 0.5.0 (2026-08-08)
 
 - Fix stamp date mismatch by using server date instead of client

data/README.md

@@ -153,45 +153,101 @@ authenticate :user, -> (u) { u.admin? } do # Supposing there is a User#admin? me
 end
 ```
 
-### Before version 0.3.0
+## Complexity
 
-You must have Redis in order to prevent double spent stamps. Otherwise it will be useless.
-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`.
+Complexity controls the base proof-of-work difficulty.
+Increasing by one doubles the work time.
+By default its value is 20 and you can change it with `ActiveHashcash.bits = 24` or by overriding the method `hashcash_bits` in the controller.
 
-You should call `ActiveHashcash::Store#clean` once a day, to remove expired stamps.
+### Penalties
 
-To upgrade from 0.2.0 you must run the migration :
+To improve protection, a penalty is added for pushy and bad IPs.
 
+### For pushy IPs
+
+A penalty is added for IPs which submit valid stamps too fast.
+The goal is to slow down attackers using a botnet.
+The penalty rules can be defined like this.
+
+```ruby
+ActiveHashcash.throttle_rules = [
+  {period: 1.hour, rate: 0.5},
+  {period: 24.hours, rate: 0.25}
+]
 ```
-rails active_hashcash:install:migrations
-rails db:migrate
+
+For every valid stamp sent less than an hour ago, a penalty of 0.5 is added.
+Then, for every valid stamp sent between 1 and 24 hours ago a penalty of 0.25 is added.
+Thus, if an IP sent 1 stamp one minute ago, and 3 others few hours ago, it adds a complexity of `(1 * 0.5 + 3 * 0.25).floor # => 1`.
+So next hashcash must have a complexity of `ActiveHashcash.bits + 1`.
+
+If you have many users behind the same IP, such as a NAT, you can either lower the rates or disable the penalty.
+In your controller, override the method `hashcash_throttle_penalty`:
+
+```ruby
+class SessionController < ApplicationController
+  include ActiveHashcash
+
+  def hashcash_throttle_penalty
+    # Only the base complexity (ActiveHashcash.bits) will apply for people with IP 1.2.3.4
+    hashcash_ip_address == "1.2.3.4" ? 0 : super
+  end
+end
 ```
 
-## Complexity
+Or, if someone is attacking you from a specific country:
+
+```ruby
+class SessionController < ApplicationController
+  include ActiveHashcash
+
+  def hashcash_throttle_penalty
+    geoip.country(hashcash_ip_address).country_code == "XX" ? super + 2 : super
+  end
+end
+```
+
+### For IPs with poor reputation
+
+The following lists are used to increase the complexity for bad IPs:
 
-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.
-However, if your application includes people with slow and old devices, then consider lowering this value, to 16 or 18.
+  - [FireHOL abusers 1 day](https://iplists.firehol.org/files/firehol_abusers_1d.netset)
+  - [FireHOL abusers 30 days](https://iplists.firehol.org/files/firehol_abusers_30d.netset)
+  - [FireHOL anonymous](https://iplists.firehol.org/files/firehol_anonymous.netset) (Tor, public proxies, etc.)
+  - [FireHOL level 1](https://iplists.firehol.org/files/firehol_level1.netset)
+  - [FireHOL level 2](https://iplists.firehol.org/files/firehol_level2.netset)
+  - [FireHOL level 3](https://iplists.firehol.org/files/firehol_level3.netset)
+  - [FireHOL level 4](https://iplists.firehol.org/files/firehol_level4.netset)
 
-You can change the minimum complexity with `ActiveHashcash.bits = 20`.
+The lists are stored in `ActiveHashcash::Reputation::IPv4Address` (single IPs) and `ActiveHashcash::Reputation::IPv4Range` (CIDR ranges). For this feature to do anything you must run the migration and schedule `ActiveHashcash::Reputation::UpdateAllScoresJob.perform_later` from a cron anywhere from once per hour to once per day.
+If you update too often you might be blocked.
+Updating reputation for ranges probably will not work before Rails 7.1 because of composite primary key + `upsert_all`.
 
-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.
+If you don't trust these external lists, don't schedule that job and delete all records of `ActiveHashcash::Reputation::IPv4Address` and `ActiveHashcash::Reputation::IPv4Range`.
 
-## Testing
+The penalty can be high enough that the proof of work is almost impossible.
+That is useful to neutralize bots.
 
-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:
+## Testing Your Application
+
+Browser tests submit the real form, so they have to compute a real stamp. At the default complexity 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
+ActiveHashcash.bits = 1
 ```
 
-In controller tests, provide the hashcash this way:
+Use `ActiveHashcash::Stamp.mint` to submit hashcash to your sensitive forms:
 
 ```ruby
-post(url, params: {hashcash: ActiveHashcash::Stamp.mint(host).to_s})
+class SessionControllerTest < ActionDispatch::IntegrationTest
+  def test_create
+    # ...
+    hashcash = ActiveHashcash::Stamp.mint(host).to_s
+    post(session_path, params: {email: email, password: password, hashcash: hashcash})
+    # ...
+  end
+end
 ```
 
 ## Limitations
@@ -202,6 +258,21 @@ A synchronous tight loop avoids the per-call async overhead of `crypto.subtle.di
 
 No `crypto.subtle` or secure context (HTTPS) is required, so it works in any environment including plain HTTP during development.
 
+### 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 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.
+
+To upgrade from 0.2.0 you must run the migration :
+
+```
+rails active_hashcash:install:migrations
+rails db:migrate
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/BaseSecrete/active_hashcash.

data/app/jobs/active_hashcash/reputation/cleanup_job.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module ActiveHashcash
+  module Reputation
+    class CleanupJob < ApplicationJob
+      def perform
+        IPv4Address.delete_zero_scores
+        IPv4Range.delete_zero_scores
+      end
+    end
+  end
+end

data/app/jobs/active_hashcash/reputation/update_abuse_score_job.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ActiveHashcash
+  module Reputation
+    class UpdateAbuseScoreJob < UpdateScoreJob
+      # Higher scores first so upsert_score keeps the max via uniq.
+      URLS = {
+        "https://iplists.firehol.org/files/firehol_abusers_1d.netset" => 2,
+        "https://iplists.firehol.org/files/firehol_abusers_30d.netset" => 1
+      }.freeze
+    end
+  end
+end

data/app/jobs/active_hashcash/reputation/update_all_scores_job.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ActiveHashcash
+  module Reputation
+    class UpdateAllScoresJob < ApplicationJob
+      DEFAULT_JOBS = [UpdateAbuseScoreJob, UpdateAnonymousScoreJob, UpdateAttackScoreJob, CleanupJob].freeze
+
+      def perform(jobs = DEFAULT_JOBS.dup)
+        if (job = jobs.shift)
+          job.perform_now
+          self.class.perform_later(jobs) if jobs.any?
+        end
+      end
+    end
+  end
+end

data/app/jobs/active_hashcash/reputation/update_anonymous_score_job.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ActiveHashcash
+  module Reputation
+    class UpdateAnonymousScoreJob < UpdateScoreJob
+      URLS = {
+        "https://iplists.firehol.org/files/firehol_anonymous.netset" => 1
+      }.freeze
+
+      def max_body_size
+        50.megabytes
+      end
+
+      def read_timeout
+        20
+      end
+    end
+  end
+end

data/app/jobs/active_hashcash/reputation/update_attack_score_job.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ActiveHashcash
+  module Reputation
+    class UpdateAttackScoreJob < UpdateScoreJob
+      # Higher scores first so upsert_score keeps the max via uniq.
+      URLS = {
+        "https://iplists.firehol.org/files/firehol_level1.netset" => 4,
+        "https://iplists.firehol.org/files/firehol_level2.netset" => 3,
+        "https://iplists.firehol.org/files/firehol_level3.netset" => 2,
+        "https://iplists.firehol.org/files/firehol_level4.netset" => 1
+      }.freeze
+    end
+  end
+end

data/app/jobs/active_hashcash/reputation/update_score_job.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require "net/http"
+require "uri"
+
+module ActiveHashcash
+  module Reputation
+    class UpdateScoreJob < ApplicationJob
+      def perform
+        entries = self.class::URLS.flat_map { |url, score| normalize(fetch(url), score) }
+        raise "Empty list" if entries.empty?
+        addresses, ranges = entries.partition { |ip, _| ip.prefix == 32 }
+        IPv4Address.transaction do
+          IPv4Address.reset_score(score_name, addresses)
+          IPv4Range.reset_score(score_name, ranges)
+        end
+      end
+
+      def score_name
+        self.class.name[/Update(\w*)ScoreJob/, 1].downcase.to_sym
+      end
+
+      def fetch(url)
+        uri = URI(url)
+        body = +""
+
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: open_timeout, read_timeout: read_timeout) do |http|
+          http.request(Net::HTTP::Get.new(uri)) do |response|
+            response.error! unless response.is_a?(Net::HTTPSuccess)
+            response.read_body do |chunk|
+              body << chunk
+              raise "Response body exceeds #{max_body_size} bytes" if body.bytesize > max_body_size
+            end
+          end
+        end
+
+        body
+      end
+
+      def open_timeout
+        5
+      end
+
+      def read_timeout
+        10
+      end
+
+      def max_body_size
+        10.megabytes
+      end
+
+      def normalize(body, score)
+        body.each_line.filter_map do |line|
+          next if (line = line.strip).blank? || line.start_with?("#", ";")
+          next if (ip = IPAddr.new(line)).private? || ip.loopback? || ip.link_local? || !ip.ipv4? || ip.prefix < IPv4Range::MIN_PREFIX
+          [ip, score]
+        rescue IPAddr::InvalidAddressError
+          next
+        end
+      end
+    end
+  end
+end

data/app/models/active_hashcash/reputation/ipv4_address.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module ActiveHashcash
+  module Reputation
+    class IPv4Address < ApplicationRecord
+      self.table_name = "active_hashcash_reputation_ipv4_addresses"
+
+      validates :id, presence: true, length: {is: 4}
+      validates :anonymous_score, inclusion: {in: 0..1}
+      validates :abuse_score, inclusion: {in: 0..2}
+      validates :attack_score, inclusion: {in: 0..4}
+
+      def self.scores(ip)
+        abuse, anonymous, attack = where(id: ActiveRecord::Type::Binary.new.serialize(IPAddr.new(ip).hton)).pick(:abuse_score, :anonymous_score, :attack_score)
+        {abuse: abuse || 0, anonymous: anonymous || 0, attack: attack || 0}
+      rescue IPAddr::InvalidAddressError
+        {abuse: 0, anonymous: 0, attack: 0}
+      end
+
+      def self.reset_score(name, entries)
+        column = :"#{name}_score"
+        entries.uniq! { |ip, _| ip }
+        transaction do
+          where(column => 1..).update_all(column => 0)
+          entries.each_slice(10_000) { |batch| upsert_score(column, batch) }
+        end
+      end
+
+      def self.upsert_score(column, entries)
+        upsert_all(
+          entries.map { |ip, value| {id: ip.hton, column => value} },
+          record_timestamps: false,
+          update_only: [column]
+        )
+      end
+
+      def self.delete_zero_scores
+        where(anonymous_score: 0, abuse_score: 0, attack_score: 0).delete_all
+      end
+    end
+  end
+end

data/app/models/active_hashcash/reputation/ipv4_range.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module ActiveHashcash
+  module Reputation
+    class IPv4Range < ApplicationRecord
+      self.table_name = "active_hashcash_reputation_ipv4_ranges"
+
+      MIN_PREFIX = 16 # Reject nets too large
+
+      validates :first_address, :last_address, presence: true, length: {is: 4}
+      validates :anonymous_score, inclusion: {in: 0..1}
+      validates :abuse_score, inclusion: {in: 0..2}
+      validates :attack_score, inclusion: {in: 0..4}
+
+      # PK probes for ancestor CIDRs /MIN_PREFIX../32 (wider prefixes are ignored).
+      scope :by_address, -> (string) {
+        ip = IPAddr.new(string)
+        binary = ActiveRecord::Type::Binary.new
+        pairs = (MIN_PREFIX..32).map do |prefix|
+          range = IPAddr.new("#{ip}/#{prefix}").to_range
+          [binary.serialize(range.first.hton), binary.serialize(range.last.hton)]
+        end
+        where(pairs.map { "(first_address = ? AND last_address = ?)" }.join(" OR "), *pairs.flatten)
+      }
+
+      def self.scores(ip)
+        abuse, anonymous, attack = by_address(ip).pick(Arel.sql("max(abuse_score), max(anonymous_score), max(attack_score)"))
+        {abuse: abuse || 0, anonymous: anonymous || 0, attack: attack || 0}
+      rescue IPAddr::InvalidAddressError
+        {abuse: 0, anonymous: 0, attack: 0}
+      end
+
+      def self.reset_score(name, entries)
+        column = :"#{name}_score"
+        entries.uniq! { |ip, _| ip }
+        transaction do
+          where(column => 1..).update_all(column => 0)
+          entries.each_slice(10_000) { |batch| upsert_score(column, batch) }
+        end
+      end
+
+      def self.upsert_score(column, entries)
+        upsert_all(
+          entries.map do |ip, value|
+            range = ip.to_range
+            {first_address: range.first.hton, last_address: range.last.hton, column => value}
+          end,
+          record_timestamps: false,
+          update_only: [column]
+        )
+      end
+
+      def self.delete_zero_scores
+        where(anonymous_score: 0, abuse_score: 0, attack_score: 0).delete_all
+      end
+    end
+  end
+end

data/app/models/active_hashcash/reputation.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ActiveHashcash
+  module Reputation
+    def self.scores(ip)
+      address = IPv4Address.scores(ip)
+      range = IPv4Range.scores(ip)
+      {
+        abuse: [address[:abuse], range[:abuse]].max,
+        anonymous: [address[:anonymous], range[:anonymous]].max,
+        attack: [address[:attack], range[:attack]].max
+      }
+    end
+  end
+end

data/app/models/active_hashcash/stamp.rb

@@ -26,6 +26,24 @@ module ActiveHashcash
       scope
     end
 
+    # Returns stamp counts per period for disjoint windows.
+    # +periods+ must be sorted shortest to longest (as ensured by ActiveHashcash.throttle_rules=).
+    def self.sum_by_periods(periods)
+      return [] if periods.blank?
+
+      cutoffs = periods.map(&:ago)
+      columns = cutoffs.each_with_index.map do |cutoff, index|
+        if index.zero?
+          sanitize_sql(["sum(CASE WHEN created_at >= ? THEN 1 ELSE 0 END)", cutoff])
+        else
+          previous_cutoff = cutoffs[index - 1]
+          sanitize_sql(["sum(CASE WHEN created_at < ? AND created_at >= ? THEN 1 ELSE 0 END)", previous_cutoff, cutoff])
+        end
+      end.join(", ")
+
+      Array.wrap(where(created_at: cutoffs.min..).pluck(Arel.sql(columns)).first)
+    end
+
     # Verify and save the hashcash stamp.
     # Saving in the database prevent from double spending the same stamp.
     def self.spend(string, resource, bits, date, options = {})

data/db/migrate/20260831130000_create_active_hashcash_reputation_ipv4s.rb

@@ -0,0 +1,54 @@
+# IPv4 reputation addresses and ranges are stored in the database.
+# This migration creates the tables for ActiveHashcash::Reputation::IPv4Address
+# and ActiveHashcash::Reputation::IPv4Range.
+# Run the following commands to add them to your Rails application:
+#
+#   rails active_hashcash:install:migrations
+#   rails db:migrate
+#
+class CreateActiveHashcashReputationIpv4s < ActiveRecord::Migration[5.2]
+  def up
+    # uint32 would have been the best choice for storing IPv4, but PostgreSQL does not support unsigned integers.
+    # So, 4-byte binary column is a trade off for best efficiency compatible with PostgreSQL, MySQL and SQLite.
+    create_table :active_hashcash_reputation_ipv4_addresses, id: false do |t|
+      t.binary :id, limit: 4, null: false, primary_key: true
+      t.integer :abuse_score, limit: 1, null: false, default: 0
+      t.integer :anonymous_score, limit: 1, null: false, default: 0
+      t.integer :attack_score, limit: 1, null: false, default: 0
+    end
+
+    create_table :active_hashcash_reputation_ipv4_ranges, primary_key: [:first_address, :last_address] do |t|
+      t.binary :first_address, limit: 4, null: false
+      t.binary :last_address, limit: 4, null: false
+      t.integer :abuse_score, limit: 1, null: false, default: 0
+      t.integer :anonymous_score, limit: 1, null: false, default: 0
+      t.integer :attack_score, limit: 1, null: false, default: 0
+    end
+
+    # For SQLite, save space by suffixing the CREATE TABLE statements by `WITHOUT ROWID`:
+    # execute <<-SQL
+    #   CREATE TABLE IF NOT EXISTS "active_hashcash_reputation_ipv4_addresses" (
+    #     "id" blob(4) NOT NULL,
+    #     "abuse_score" integer(1) DEFAULT 0 NOT NULL,
+    #     "anonymous_score" integer(1) DEFAULT 0 NOT NULL,
+    #     "attack_score" integer(1) DEFAULT 0 NOT NULL,
+    #     PRIMARY KEY ("id")
+    #   ) WITHOUT ROWID;
+    # SQL
+    # execute <<-SQL
+    #   CREATE TABLE IF NOT EXISTS "active_hashcash_reputation_ipv4_ranges" (
+    #     "first_address" blob(4) NOT NULL,
+    #     "last_address" blob(4) NOT NULL,
+    #     "abuse_score" integer(1) DEFAULT 0 NOT NULL,
+    #     "anonymous_score" integer(1) DEFAULT 0 NOT NULL,
+    #     "attack_score" integer(1) DEFAULT 0 NOT NULL,
+    #     PRIMARY KEY ("first_address", "last_address")
+    #   ) WITHOUT ROWID;
+    # SQL
+  end
+
+  def down
+    drop_table :active_hashcash_reputation_ipv4_addresses
+    drop_table :active_hashcash_reputation_ipv4_ranges
+  end
+end

data/lib/active_hashcash/engine.rb

@@ -3,5 +3,11 @@ module ActiveHashcash
     config.assets.paths << File.expand_path("../..", __FILE__) if config.respond_to?(:assets)
 
     isolate_namespace ActiveHashcash
+
+    initializer "active_hashcash.inflections" do
+      ActiveSupport::Inflector.inflections(:en) do |inflect|
+        inflect.acronym "IPv4"
+      end
+    end
   end
 end

data/lib/active_hashcash/version.rb

@@ -1,3 +1,3 @@
 module ActiveHashcash
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/active_hashcash.rb

@@ -14,8 +14,8 @@ require "active_hashcash/engine"
 #     before_action :check_hashcash, only: :create
 #   end
 #
-# Your are welcome to override most of the methods to customize to your needs.
-# For example, if your app runs behind a loab balancer you should probably override #hashcash_ip_address.
+# You are welcome to override most of the methods to customize to your needs.
+# For example, if your app runs behind a load balancer you should probably override #hashcash_ip_address.
 #
 module ActiveHashcash
   extend ActiveSupport::Concern
@@ -28,10 +28,41 @@ module ActiveHashcash
 
   # This is base complexity.
   # Consider lowering it to not exclude people with old and slow devices.
-  mattr_accessor :bits, instance_accessor: false, default: 16
+  mattr_accessor :bits, instance_accessor: false, default: 20
+
+  # Flexible complexity penalty rules applied to pushy IP addresses.
+  # Each rule must be a hash with:
+  # - :period => time window considered (e.g. 5.minutes, 1.hour, 1.day)
+  # - :rate => multiplier applied to the number of stamps in that window
+  # Assignment sorts rules from shortest to longest period.
+  #
+  # Example:
+  #   ActiveHashcash.throttle_rules = [
+  #     {period: 5.minutes, rate: 0.5},
+  #     {period: 1.hour, rate: 0.34},
+  #     {period: 1.day, rate: 0.25}
+  #   ]
+  mattr_reader :throttle_rules, instance_accessor: false, default: [
+    {period: 1.hour, rate: 0.5},
+    {period: 24.hours, rate: 0.25}
+  ]
+
+  def self.throttle_rules=(rules)
+    rules&.each do |rule|
+      raise ArgumentError, "ActiveHashcash.throttle_rules period must be present" if rule[:period].nil?
+      raise ArgumentError, "ActiveHashcash.throttle_rules rate must be >= 0" if rule[:rate].to_f.negative?
+    end
+    @@throttle_rules = rules && rules.sort_by { |rule| rule[:period] }
+  end
 
   mattr_accessor :date_format, instance_accessor: false, default: "%y%m%d"
 
+  # Base controller class used by ActiveHashcash helpers/integration.
+  # Override this if your application subclasses the default Rails
+  # `ActionController::Base` (e.g. to apply common behavior across controllers).
+
+  # By default ActiveHashcash extends `ActionController::Base`, but you can change it to any controller,
+  # such as `AdminController` to handle authentication for the dashboard.
   mattr_accessor :base_controller_class, default: "ActionController::Base"
 
   # Call that method via a before_action when the form is submitted:
@@ -60,7 +91,7 @@ module ActiveHashcash
     request.remote_ip
   end
 
-  # Return current request path to be saved to the sucessful ActiveHash::Stamp.
+  # Return current request path to be saved to the successful ActiveHashcash::Stamp.
   # If multiple forms are protected via hashcash this is an interesting info.
   def hashcash_request_path
     request.path
@@ -73,20 +104,29 @@ module ActiveHashcash
 
   # This is the resource used to build the hashcash stamp.
   # By default the host name is returned.
-  # It' should be good for most cases and prevent from reusing the same stamp between sites.
+  # It should be good for most cases and prevent from reusing the same stamp between sites.
   def hashcash_resource
     ActiveHashcash.resource || request.host
   end
 
   # Returns the complexity, the higher the slower it is.
-  # Complexity is increased logarithmicly for each IP during the last 24H to slowdown brute force attacks.
-  # The minimun value returned is ActiveHashcash.bits.
+  # Eventually adds penalties for bad and pushy IPs.
   def hashcash_bits
-    if (previous_stamp_count = ActiveHashcash::Stamp.where(ip_address: hashcash_ip_address).where(created_at: 1.day.ago..).count) > 0
-      (ActiveHashcash.bits + Math.log2(previous_stamp_count)).floor
-    else
-      ActiveHashcash.bits
-    end
+    (ActiveHashcash.bits + hashcash_throttle_penalty + hashcash_reputation_penalty).floor
+  end
+
+  # Compute a penalty for pushy IPs.
+  # The penalty rules can be defined with `ActiveHashcash.throttle_rules`.
+  def hashcash_throttle_penalty
+    rules = ActiveHashcash.throttle_rules || []
+    periods = rules.map { |rule| rule[:period] }
+    counts = ActiveHashcash::Stamp.where(ip_address: hashcash_ip_address).sum_by_periods(periods)
+    rules.each_with_index.sum { |rule, index| counts[index].to_i * rule[:rate].to_f }
+  end
+
+  # Compute a reputation penalty for the current IP.
+  def hashcash_reputation_penalty
+    Reputation.scores(hashcash_ip_address).values.sum * 4
   end
 
   # Override if you want to rename the hashcash param.
@@ -111,7 +151,7 @@ module ActiveHashcash
     # Override me for your own needs.
   end
 
-  # Call it inside the form that have to be protected and don't forget to initialize the JavaScript Hascash.setup().
+  # Call it inside the form that have to be protected and don't forget to initialize the JavaScript Hashcash.setup().
   # Unless you need something really special, you should not need to override this method.
   #
   #   <% form_for model do |form| %>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_hashcash
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Alexis Bernard
@@ -31,6 +31,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- AGENTS.md
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
@@ -45,8 +46,17 @@ files:
 - app/helpers/active_hashcash/application_helper.rb
 - app/helpers/active_hashcash/stamps_helper.rb
 - app/jobs/active_hashcash/application_job.rb
+- app/jobs/active_hashcash/reputation/cleanup_job.rb
+- app/jobs/active_hashcash/reputation/update_abuse_score_job.rb
+- app/jobs/active_hashcash/reputation/update_all_scores_job.rb
+- app/jobs/active_hashcash/reputation/update_anonymous_score_job.rb
+- app/jobs/active_hashcash/reputation/update_attack_score_job.rb
+- app/jobs/active_hashcash/reputation/update_score_job.rb
 - app/mailers/active_hashcash/application_mailer.rb
 - app/models/active_hashcash/application_record.rb
+- app/models/active_hashcash/reputation.rb
+- app/models/active_hashcash/reputation/ipv4_address.rb
+- app/models/active_hashcash/reputation/ipv4_range.rb
 - app/models/active_hashcash/stamp.rb
 - app/views/active_hashcash/addresses/index.html.erb
 - app/views/active_hashcash/assets/_logo.svg.erb
@@ -71,6 +81,7 @@ files:
 - config/locales/pt.yml
 - config/routes.rb
 - db/migrate/20240215143453_create_active_hashcash_stamps.rb
+- db/migrate/20260831130000_create_active_hashcash_reputation_ipv4s.rb
 - lib/active_hashcash.rb
 - lib/active_hashcash/engine.rb
 - lib/active_hashcash/version.rb