altcha 2.0.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa3024a2d52d47905ebe5d5c46580e25254eea39f3e3594518504753941857f0
-  data.tar.gz: 82f3ec91b73f8fd0445e023213b0217344ed1bc606bbdcd5df1c6366428c4a2f
+  metadata.gz: f3f8c54a53e1c95984a1f46cc9420708fce3a3564b727ac3439c12da1dc922f3
+  data.tar.gz: f036c9affe9baebe5d23a2b9146ac967bb1482b604bc6db0d71c95b7b07b0605
 SHA512:
-  metadata.gz: 65ce019b295fb69ad6b7a84c0ed3230265275ce14bd28dc4cfb238b4a3c34f54255c2e38e5369cb437dabf7de39b26cad6c7882dc1c25856b58b5d41eebe2b0c
-  data.tar.gz: 22784f9ace9393b325603e72ec476d08f504af8ec775f8e5fa1cfe0b9c1774e81ab481027870f961364b07ea273ccd414a645d018007d5dd7576b9af5e4f4b34
+  metadata.gz: 34e5b230a973ad0b4e90da5389b45bd1ef383f8329ad38747e961a98b49f525c4262a9d51f13be7026afc74ce6340188d47f6b2f94233bca751116cbab900ad3
+  data.tar.gz: 25c5a676ab422049e48185cb12ada7332194bbbe13dd2688a77b54cbfbc0be65a7b0afdf258af0aa2a8e91aeec5da97b3ebfe9515a1a199a3d365ff54d1f53b5

data/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [3.0.0] - 2026-10-04
+
+Brings `Altcha::V2` in line with the reference JS implementation: challenges, solutions and signatures now interoperate in both directions.
+
+### Breaking changes
+
+- Ruby 3.0 or newer is required. v2 already needed it: `OpenSSL.fixed_length_secure_compare` does not exist on Ruby 2.7.
+- `ARGON2ID` uses `memory_cost` exactly, in KiB; it was rounded to a power of two before. `memory_cost` is now required and has no 64 MiB default. ARGON2ID challenges created earlier with a memory cost that is not a power of two no longer verify.
+- `hmac_algorithm` accepts only `'SHA-256'`, `'SHA-384'` and `'SHA-512'`, matched exactly. Anything else, including `'SHA-1'`, lowercase names and `nil`, raises `ArgumentError`. Before, unknown values silently used SHA-256.
+- `verify_fields_hash` raises `ArgumentError` for any algorithm other than `'SHA-256'`, `'SHA-384'` or `'SHA-512'`. Before, unknown values silently used SHA-256.
+- `verify_solution` raises `ArgumentError` when `hmac_signature_secret` is `nil` or `''`.
+- `create_challenge` treats `''` secrets as unset, as JS does. An empty `hmac_signature_secret` returns an unsigned challenge, and an empty `hmac_key_signature_secret` adds no `keySignature`.
+- `solve_challenge` gives up after 90 seconds by default and returns `nil`. Pass `timeout: nil` to keep the old unlimited behaviour.
+- `expires_at` is compared with sub-second precision, so there is no longer up to 1 second of extra validity. `expires_at: 0` means "no expiry" instead of "expired".
+- In `uint32` counter mode, `verify_solution` accepts only whole-number counters from 0 to 2^32−1. Values that wrap to a valid counter, such as `c + 2^32`, are rejected as `invalid_solution`. JS accepts them, so this is stricter.
+- The signed JSON now includes unknown and `null` challenge parameters exactly as received, so adding a field to a challenge invalidates its signature. A challenge without `keyLength` or `keyPrefix` no longer has the defaults added to its signed JSON.
+- `canonical_json` output changed for floats, integer-like keys, keys sorted by UTF-16 code unit, and objects inside arrays (see below). Challenges that were signed before upgrading and contain such `data` fail verification once.
+
+### Added
+
+- `counter_mode` option (`'uint32'`, the default, or `'string'`) for `create_challenge`, `solve_challenge` and `verify_solution`, matching JS `counterMode`. Unknown values raise `ArgumentError`.
+- `hmac_algorithm` option for `create_challenge`. It is used for both the challenge signature and `keySignature`.
+- `timeout` option for `solve_challenge`, in milliseconds (default `90_000`).
+- `ChallengeParameters#extra`, which holds parameter keys without a matching attribute so they are signed exactly as received.
+
+### Fixed
+
+- `canonical_json` writes numbers like JS `JSON.stringify` (`1.0` → `1`, `1e-7` → `1e-7`, integers above 2^53 rounded to a double) and orders keys like JS: integer-like keys first in numeric order, other keys by UTF-16 code unit, objects inside arrays unsorted.
+- `key_prefix` is lowercased in `create_challenge`, and `solve_challenge` and `verify_solution` compare it case-insensitively. Before, a signed uppercase prefix never verified and made `solve_challenge` loop forever.
+- On the `keySignature` fast path, a `derivedKey` that is not an even-length hex string is rejected. Before, odd-length or non-hex strings could decode to the real key and verify.
+- `verify_solution` returns a result instead of raising for any malformed client input:
+  - a non-numeric `counter`;
+  - a `derivedKey` that is not a string or not valid UTF-8;
+  - a non-numeric `expiresAt`;
+  - a challenge `signature` that is not a string;
+  - challenge parameters containing invalid UTF-8.
+- `verify_server_signature` returns a result for an unsupported `algorithm` or a non-string `verificationData`. Before, unknown algorithms fell back to SHA-256. A non-numeric or zero `expire` never expires, as in JS.
+- `verify_fields_hash` hashes falsy values (`nil`, `false`, `0`, `''`) as empty strings, as JS `String(value || '')` does.
+- A `keySignature` or secret that is `''` (or another falsy value) skips the fast path and re-derives the key, as in JS.

data/Gemfile.lock

@@ -1,14 +1,17 @@
 PATH
   remote: .
   specs:
-    altcha (2.0.1)
+    altcha (3.0.0)
       base64
 
 GEM
   remote: https://rubygems.org/
   specs:
+    argon2-kdf (1.0.0)
+      fiddle
     base64 (0.3.0)
     diff-lcs (1.6.2)
+    fiddle (1.1.8)
     rake (13.4.2)
     rspec (3.13.2)
       rspec-core (~> 3.13.0)
@@ -30,6 +33,7 @@ PLATFORMS
 
 DEPENDENCIES
   altcha!
+  argon2-kdf (>= 0.3)
   bundler (~> 4.0)
   rake (~> 13.3)
   rspec (~> 3.13)

data/README.md

@@ -4,7 +4,7 @@ The ALTCHA Ruby Library is a lightweight, zero-dependency library designed for c
 
 ## Compatibility
 
-- Ruby 2.7+
+- Ruby 3.0+
 
 ## Examples
 
@@ -122,14 +122,16 @@ Creates a new v2 challenge.
 | `algorithm` | `String` | — | Key derivation algorithm: `SHA-256`, `SHA-384`, `SHA-512`, `PBKDF2/SHA-256`, `PBKDF2/SHA-384`, `PBKDF2/SHA-512`, `SCRYPT`, `ARGON2ID`. |
 | `cost` | `Integer` | — | Algorithm cost (iterations for PBKDF2/SHA, N for SCRYPT). |
 | `counter` | `Integer` | `nil` | Pre-compute a deterministic key prefix from this counter value. |
+| `counter_mode` | `String` | `'uint32'` | How the counter is appended to the nonce: `'uint32'` (4-byte big-endian) or `'string'` (decimal text, as JS `counterMode: 'string'`); anything else raises `ArgumentError`. Pass the same value to `solve_challenge` and `verify_solution`. |
 | `data` | `Hash` | `nil` | Arbitrary metadata to embed in the challenge. |
-| `expires_at` | `Integer, Time` | `nil` | Expiration timestamp (Unix seconds or `Time`). |
-| `hmac_signature_secret` | `String` | `nil` | Signs the challenge parameters. Required for `verify_solution`. |
-| `hmac_key_signature_secret` | `String` | `nil` | Signs the derived key (fast-path verification). Requires `counter`. |
+| `expires_at` | `Integer, Time` | `nil` | Expiration timestamp (Unix seconds or `Time`). Expired once the current time passes it, compared with sub-second precision; `0` means no expiry. |
+| `hmac_algorithm` | `String` | `'SHA-256'` | HMAC algorithm for the challenge signature and key signature: `'SHA-256'`, `'SHA-384'` or `'SHA-512'` (exact, as in altcha-lib JS); anything else raises `ArgumentError`. Pass the same value to `verify_solution`. |
+| `hmac_signature_secret` | `String` | `nil` | Signs the challenge parameters. Required for `verify_solution`. `nil` or `''` returns an unsigned challenge (no `key_signature` either). |
+| `hmac_key_signature_secret` | `String` | `nil` | Signs the derived key (fast-path verification). Requires `counter`. `nil` or `''` adds no `key_signature`. |
 | `key_length` | `Integer` | `32` | Derived key length in bytes. |
-| `key_prefix` | `String` | `'00'` | Hex prefix the derived key must start with. |
+| `key_prefix` | `String` | `'00'` | Hex prefix the derived key must start with. Lowercased; solve and verify also match prefixes case-insensitively. |
 | `key_prefix_length` | `Integer` | `key_length / 2` | Bytes of the derived key used as prefix in deterministic mode. |
-| `memory_cost` | `Integer` | `nil` | Memory cost in KiB (`ARGON2ID`), or block size `r` (`SCRYPT`). |
+| `memory_cost` | `Integer` | `nil` | Memory cost in KiB (`ARGON2ID`, required; used exactly, not rounded), or block size `r` (`SCRYPT`). |
 | `parallelism` | `Integer` | `nil` | Parallelism factor (`ARGON2ID`, `SCRYPT`). |
 
 ---
@@ -144,6 +146,8 @@ Solves a challenge by iterating counter values until the derived key starts with
 | `max_counter` | `Integer, nil` | `nil` | Safety cap on the counter. Returns `nil` if exceeded. |
 | `counter_start` | `Integer` | `0` | Starting counter value. |
 | `counter_step` | `Integer` | `1` | Counter increment per iteration. |
+| `counter_mode` | `String` | `'uint32'` | `'uint32'` or `'string'`; must match the challenge's `counter_mode`. |
+| `timeout` | `Numeric, nil` | `90_000` | Milliseconds before giving up and returning `nil` (JS default). `nil` or `0` disables it. |
 
 ---
 
@@ -155,9 +159,10 @@ Verifies a submitted solution.
 |---|---|---|
 | `challenge` | `Challenge` | The original challenge. |
 | `solution` | `Solution` | The submitted solution. |
-| `hmac_signature_secret:` | `String` | Must match the secret used in `create_challenge`. |
-| `hmac_key_signature_secret:` | `String, nil` | Required when `key_signature` is present. |
-| `hmac_algorithm:` | `String` | HMAC digest algorithm (`SHA-256`, `SHA-384`, `SHA-512`). Default: `SHA-256`. |
+| `hmac_signature_secret:` | `String` | Must match the secret used in `create_challenge`. `nil` or `''` raises `ArgumentError`. |
+| `hmac_key_signature_secret:` | `String, nil` | Enables the fast path when `key_signature` is present. `nil` or `''` re-derives the key instead. |
+| `hmac_algorithm:` | `String` | HMAC digest algorithm (`SHA-256`, `SHA-384`, `SHA-512`); anything else raises `ArgumentError`. Default: `SHA-256`. |
+| `counter_mode:` | `String` | `'uint32'` or `'string'`; must match the challenge's `counter_mode`. Default: `uint32`. |
 
 **`VerifySolutionResult`**
 
@@ -166,14 +171,14 @@ Verifies a submitted solution.
 | `verified` | `Boolean` | `true` if the solution is valid. |
 | `expired` | `Boolean` | `true` if the challenge has expired. |
 | `invalid_signature` | `Boolean, nil` | `true` if the challenge signature is missing or wrong. |
-| `invalid_solution` | `Boolean, nil` | `true` if the derived key does not match. |
+| `invalid_solution` | `Boolean, nil` | `true` if the derived key does not match, or the solution is malformed (`counter` not a number, or in `uint32` mode not a whole number in `0..2^32-1`; `derived_key` not an even-length hex string). |
 | `time` | `Integer` | Verification time in milliseconds. |
 
 ---
 
 ### `Altcha::V2.verify_server_signature(payload:, hmac_secret:)` → `VerifyServerSignatureResult`
 
-Verifies a server signature payload issued by the ALTCHA backend.
+Verifies a server signature payload issued by the ALTCHA backend. A payload `algorithm` other than `SHA-256`, `SHA-384` or `SHA-512` gives `invalid_signature: true`.
 
 | Parameter | Type | Description |
 |---|---|---|
@@ -195,7 +200,7 @@ Verifies a server signature payload issued by the ALTCHA backend.
 
 ### `Altcha::V2.verify_fields_hash(form_data:, fields:, fields_hash:, algorithm: 'SHA-256')` → `Boolean`
 
-Verifies the SHA digest of selected form fields, matching the `fieldsHash` included in `verification_data`.
+Verifies the SHA digest of selected form fields, matching the `fieldsHash` included in `verification_data`. Falsy values (`nil`, `false`, `0`, `''`, as in JS) hash as empty strings. `algorithm` must be `'SHA-256'`, `'SHA-384'` or `'SHA-512'`; anything else raises `ArgumentError`.
 
 ---
 
@@ -207,7 +212,7 @@ Parses a URL-encoded `verificationData` string into a typed Hash. Booleans, inte
 
 ### `Altcha::V2.canonical_json(obj)` → `String`
 
-Produces a canonical (alphabetically sorted keys, compact) JSON string. Used internally for signing.
+Produces a canonical compact JSON string, byte-identical to JS `JSON.stringify(sortKeys(obj))`. Object keys are sorted, except that integer-like keys (`"2"`, `"10"`) come first in numeric order as in JS, and objects inside arrays keep their key order. Numbers are formatted like JS `JSON.stringify` (`1.0` → `1`, `1e-7` → `1e-7`, integers beyond 2^53 rounded to the nearest double). Used internally for signing.
 
 ---
 
@@ -219,6 +224,8 @@ Produces a canonical (alphabetically sorted keys, compact) JSON string. Used int
 - `.from_json(string)` / `#to_json`
 
 **`Altcha::V2::ChallengeParameters`** — all parameters embedded in a challenge.
+- `extra` — `Hash` of parsed parameter keys without a non-nil attribute (unknown fields, explicit `null`s). Serialized and signed verbatim, so challenges from other implementations verify; injected fields fail the signature check.
+- `key_length` / `key_prefix` — default to `32` / `'00'` when absent from a parsed challenge, but absent keys are not added to the signed JSON.
 
 **`Altcha::V2::Solution`** — solution returned by `solve_challenge`.
 - `counter` — `Integer`

data/altcha.gemspec

@@ -12,7 +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"
+  spec.required_ruby_version = ">= 3.0"
 
   # 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.
@@ -25,6 +25,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "base64"
 
+  spec.add_development_dependency "argon2-kdf", ">= 0.3"
   spec.add_development_dependency "bundler", "~> 4.0"
   spec.add_development_dependency "rake", "~> 13.3"
   spec.add_development_dependency "rspec", "~> 3.13"

data/lib/altcha/v2.rb

@@ -12,15 +12,27 @@ module Altcha
   module V2
     DEFAULT_KEY_LENGTH = 32
     DEFAULT_KEY_PREFIX = '00'
+    # solve_challenge timeout in milliseconds (JS solveChallenge default).
+    DEFAULT_SOLVE_TIMEOUT = 90_000
+    # Even-length hex string (case-insensitive, like JS parseInt).
+    HEX_PATTERN = /\A(?:[0-9a-fA-F]{2})*\z/.freeze
 
     # All parameters embedded in a v2 challenge.
     class ChallengeParameters
-      attr_accessor :algorithm, :nonce, :salt, :cost, :key_length, :key_prefix,
-                    :key_signature, :memory_cost, :parallelism, :expires_at, :data
+      # camelCase keys backed by attributes; any other key goes to #extra.
+      KEYS = %w[algorithm cost data expiresAt keyLength keyPrefix keySignature
+                memoryCost nonce parallelism salt].freeze
 
+      attr_accessor :algorithm, :nonce, :salt, :cost, :key_signature, :memory_cost,
+                    :parallelism, :expires_at, :data, :extra
+      attr_writer :key_length, :key_prefix
+
+      # extra: keys from a parsed challenge with no non-nil attribute (unknown
+      # fields, explicit nulls). Serialized verbatim so the signed canonical JSON
+      # matches what the issuer signed, as JS canonicalJSON does.
       def initialize(algorithm:, nonce:, salt:, cost:, key_length: DEFAULT_KEY_LENGTH,
                      key_prefix: DEFAULT_KEY_PREFIX, key_signature: nil,
-                     memory_cost: nil, parallelism: nil, expires_at: nil, data: nil)
+                     memory_cost: nil, parallelism: nil, expires_at: nil, data: nil, extra: {})
         @algorithm    = algorithm
         @nonce        = nonce
         @salt         = salt
@@ -32,24 +44,36 @@ module Altcha
         @parallelism  = parallelism
         @expires_at   = expires_at
         @data         = data
+        @extra        = extra
+      end
+
+      # A parsed challenge may omit keyLength/keyPrefix: use the defaults for
+      # solving and verifying, but keep them out of the signed JSON.
+      def key_length
+        @key_length.nil? ? DEFAULT_KEY_LENGTH : @key_length
       end
 
-      # Serializes to a plain Hash with camelCase keys, omitting nil optional fields.
-      # The resulting hash must be stable across round-trips for HMAC signing to work.
+      def key_prefix
+        @key_prefix.nil? ? DEFAULT_KEY_PREFIX : @key_prefix
+      end
+
+      # Serializes to a plain Hash with camelCase keys: non-nil attributes plus
+      # #extra. Must reproduce the issuer's parameters exactly for HMAC signing.
       def to_h
         h = {
-          'algorithm' => algorithm,
-          'cost'      => cost,
-          'keyLength' => key_length,
-          'keyPrefix' => key_prefix,
-          'nonce'     => nonce,
-          'salt'      => salt,
-        }
-        h['data']         = data          unless data.nil?
-        h['expiresAt']    = expires_at    unless expires_at.nil?
-        h['keySignature'] = key_signature unless key_signature.nil?
-        h['memoryCost']   = memory_cost   unless memory_cost.nil?
-        h['parallelism']  = parallelism   unless parallelism.nil?
+          'algorithm'    => algorithm,
+          'cost'         => cost,
+          'data'         => data,
+          'expiresAt'    => expires_at,
+          'keyLength'    => @key_length,
+          'keyPrefix'    => @key_prefix,
+          'keySignature' => key_signature,
+          'memoryCost'   => memory_cost,
+          'nonce'        => nonce,
+          'parallelism'  => parallelism,
+          'salt'         => salt
+        }.compact
+        extra.each { |key, value| h[key] = value unless h.key?(key) }
         h
       end
 
@@ -85,13 +109,14 @@ module Altcha
             nonce:        p['nonce'],
             salt:         p['salt'],
             cost:         p['cost'],
-            key_length:   p.fetch('keyLength',  DEFAULT_KEY_LENGTH),
-            key_prefix:   p.fetch('keyPrefix',  DEFAULT_KEY_PREFIX),
+            key_length:   p['keyLength'],
+            key_prefix:   p['keyPrefix'],
             key_signature: p['keySignature'],
             memory_cost:  p['memoryCost'],
             parallelism:  p['parallelism'],
             expires_at:   p['expiresAt'],
-            data:         p['data']
+            data:         p['data'],
+            extra:        p.reject { |key, value| !value.nil? && ChallengeParameters::KEYS.include?(key) }
           ),
           signature: data['signature']
         )
@@ -222,20 +247,22 @@ module Altcha
 
     # Options for V2.create_challenge.
     class CreateChallengeOptions
-      attr_accessor :algorithm, :cost, :counter, :data, :expires_at,
-                    :hmac_signature_secret, :hmac_key_signature_secret,
+      attr_accessor :algorithm, :cost, :counter, :counter_mode, :data, :expires_at,
+                    :hmac_algorithm, :hmac_signature_secret, :hmac_key_signature_secret,
                     :key_length, :key_prefix, :key_prefix_length,
                     :memory_cost, :parallelism
 
-      def initialize(algorithm:, cost:, counter: nil, data: nil,
-                     expires_at: nil, hmac_signature_secret: nil,
+      def initialize(algorithm:, cost:, counter: nil, counter_mode: 'uint32', data: nil,
+                     expires_at: nil, hmac_algorithm: 'SHA-256', hmac_signature_secret: nil,
                      hmac_key_signature_secret: nil, key_length: nil, key_prefix: nil,
                      key_prefix_length: nil, memory_cost: nil, parallelism: nil)
         @algorithm                = algorithm
         @cost                     = cost
         @counter                  = counter
+        @counter_mode             = counter_mode
         @data                     = data
         @expires_at               = expires_at
+        @hmac_algorithm           = hmac_algorithm
         @hmac_signature_secret    = hmac_signature_secret
         @hmac_key_signature_secret = hmac_key_signature_secret
         @key_length               = key_length
@@ -250,25 +277,111 @@ module Altcha
     # Module-level functions
     # -------------------------------------------------------------------------
 
-    # Produces a canonical (sorted-key, compact) JSON string.
+    # Largest integer a JS number holds exactly (Number.MAX_SAFE_INTEGER).
+    MAX_SAFE_INTEGER = (2**53) - 1
+
+    # Largest array index; JSON.stringify emits keys "0".."4294967294" first.
+    MAX_ARRAY_INDEX = (2**32) - 2
+
+    # Produces a canonical (sorted-key, compact) JSON string, byte-identical to
+    # JS JSON.stringify(sortKeys(obj)): keys and numbers are ordered/formatted
+    # like JS so signatures match across implementations and survive a JS
+    # parse/stringify round-trip.
     def self.canonical_json(obj)
+      js_json(obj, true)
+    end
+
+    # sort_keys mirrors JS sortKeys, which recurses into objects but returns
+    # arrays (and any objects inside them) untouched.
+    def self.js_json(obj, sort_keys)
       case obj
       when Hash
-        pairs = obj.sort_by { |k, _| k.to_s }
-                   .map { |k, v| "#{k.to_s.to_json}:#{canonical_json(v)}" }
+        pairs = js_key_order(obj, sort_keys).map { |k, v| "#{k.to_json}:#{js_json(v, sort_keys)}" }
         "{#{pairs.join(',')}}"
       when Array
-        "[#{obj.map { |v| canonical_json(v) }.join(',')}]"
+        "[#{obj.map { |v| js_json(v, false) }.join(',')}]"
+      when Integer, Float
+        js_number(obj)
       else
         obj.to_json
       end
     end
+    private_class_method :js_json
+
+    # JS object key order: array-index keys ascending numerically, then the
+    # remaining keys in insertion order. sortKeys inserts them sorted with
+    # Array#sort, which compares UTF-16 code units.
+    def self.js_key_order(hash, sort_keys)
+      pairs = hash.map { |k, v| [k.to_s, v] }
+      index_pairs, named_pairs = pairs.partition { |k, _| array_index_key?(k) }
+      named_pairs = named_pairs.sort_by { |k, _| k.encode(Encoding::UTF_16BE) } if sort_keys
+      index_pairs.sort_by { |k, _| k.to_i } + named_pairs
+    end
+    private_class_method :js_key_order
+
+    # Invalid-UTF-8 keys (e.g. JSON-parsed lone surrogates) are never indices;
+    # checking first keeps the regex from raising on them.
+    def self.array_index_key?(key)
+      key.valid_encoding? && /\A(?:0|[1-9][0-9]{0,9})\z/.match?(key) && key.to_i <= MAX_ARRAY_INDEX
+    end
+    private_class_method :array_index_key?
+
+    # ECMAScript Number::toString as used by JSON.stringify; non-finite → null.
+    # Float#to_s yields the shortest round-trip digits, same as JS.
+    def self.js_number_to_s(float)
+      return 'null' unless float.finite?
+      return '0' if float.zero?
+
+      mantissa, exponent = float.abs.to_s.split('e')
+      int_part, frac_part = mantissa.split('.')
+      all_digits = int_part + frac_part.to_s
+      digits     = all_digits.sub(/\A0+/, '')
+      # n: position of the decimal point relative to the first significant digit.
+      n      = int_part.length + exponent.to_i - (all_digits.length - digits.length)
+      digits = digits.sub(/0+\z/, '')
+      k      = digits.length
+
+      s = if k <= n && n <= 21
+            digits + ('0' * (n - k))
+          elsif n.positive? && n <= 21
+            "#{digits[0, n]}.#{digits[n..]}"
+          elsif n > -6 && n <= 0
+            "0.#{'0' * -n}#{digits}"
+          else
+            e   = n - 1
+            exp = e.negative? ? "e-#{-e}" : "e+#{e}"
+            k == 1 ? "#{digits}#{exp}" : "#{digits[0]}.#{digits[1..]}#{exp}"
+          end
+      float.negative? ? "-#{s}" : s
+    end
+    private_class_method :js_number_to_s
+
+    # JS Number#toString for a JSON-number value (Integer or finite Float).
+    def self.js_number(num)
+      num.is_a?(Integer) && num.abs <= MAX_SAFE_INTEGER ? num.to_s : js_number_to_s(num.to_f)
+    end
+    private_class_method :js_number
+
+    # Counter encodings supported by altcha-lib (JS PasswordBuffer).
+    COUNTER_MODES = %w[uint32 string].freeze
+
+    # Largest counter in uint32 mode (4-byte big-endian).
+    MAX_UINT32 = (2**32) - 1
 
     # Builds the password buffer (nonce bytes + counter) used for key derivation.
-    # Counter is encoded as a 4-byte big-endian unsigned integer.
-    def self.make_password(nonce_bytes, counter)
-      nonce_bytes + [counter].pack('N')
+    # 'uint32': 4-byte big-endian unsigned integer (wraps mod 2^32 like JS setUint32).
+    # 'string': the counter's decimal string (JS n.toString()), UTF-8 encoded.
+    def self.make_password(nonce_bytes, counter, counter_mode = 'uint32')
+      validate_counter_mode(counter_mode)
+      nonce_bytes + (counter_mode == 'string' ? js_number(counter) : [counter].pack('N'))
+    end
+
+    def self.validate_counter_mode(counter_mode)
+      return if COUNTER_MODES.include?(counter_mode)
+
+      raise ArgumentError, "Unsupported counter mode: #{counter_mode.inspect} (expected #{COUNTER_MODES.join(', ')})"
     end
+    private_class_method :validate_counter_mode
 
     # Derives a key from the given parameters, salt, and password bytes.
     def self.derive_key(parameters, salt_bytes, password_bytes)
@@ -282,16 +395,22 @@ module Altcha
         rescue LoadError
           raise LoadError, "Add 'argon2-kdf' to your Gemfile to use the ARGON2ID algorithm"
         end
-        # argon2-kdf's `m` is log2(memory_cost_in_KiB) — convert from KiB.
-        m_kib = parameters.memory_cost || 65536
-        Argon2::KDF.argon2id(
-          password_bytes,
-          salt:   salt_bytes,
-          t:      parameters.cost,
-          m:      Math.log2(m_kib).round,
-          p:      parameters.parallelism || 1,
-          length: key_len
+        memory_cost = parameters.memory_cost
+        raise ArgumentError, 'ARGON2ID requires memory_cost (KiB)' if memory_cost.nil?
+
+        # argon2-kdf's public API takes log2(memory), which cannot express
+        # non-power-of-two memoryCost values, so call its libargon2 binding
+        # directly with the exact KiB value (as node crypto.argon2 does).
+        hash   = Fiddle::Pointer.malloc(key_len, Fiddle::RUBY_FREE)
+        status = Argon2::KDF::FFI.argon2id_hash_raw(
+          parameters.cost, memory_cost, parameters.parallelism || 1,
+          Fiddle::Pointer[password_bytes], password_bytes.bytesize,
+          Fiddle::Pointer[salt_bytes], salt_bytes.bytesize,
+          hash, key_len
         )
+        raise Argon2::KDF::Error, Argon2::KDF::FFI.argon2_error_message(status).to_s unless status.zero?
+
+        hash[0, key_len]
       when /\APBKDF2\//
         digest = case alg
                  when 'PBKDF2/SHA-512' then 'SHA512'
@@ -331,16 +450,22 @@ module Altcha
       end
     end
 
+    # SHA algorithms supported for HMAC (JS HmacAlgorithm) and plain hashes → OpenSSL digest.
+    SHA_DIGESTS = { 'SHA-256' => 'SHA256', 'SHA-384' => 'SHA384', 'SHA-512' => 'SHA512' }.freeze
+
     # Computes an HMAC hex digest using the specified algorithm ('SHA-256' etc.).
+    # Raises ArgumentError for any algorithm outside SHA_DIGESTS.
     def self.hmac_hex(data, key, algorithm = 'SHA-256')
-      digest = case algorithm
-               when 'SHA-384' then 'SHA384'
-               when 'SHA-512' then 'SHA512'
-               else 'SHA256'
-               end
-      OpenSSL::HMAC.hexdigest(digest, key, data)
+      OpenSSL::HMAC.hexdigest(sha_digest(algorithm), key, data)
     end
 
+    def self.sha_digest(algorithm)
+      SHA_DIGESTS.fetch(algorithm) do
+        raise ArgumentError, "Unsupported algorithm: #{algorithm.inspect} (expected #{SHA_DIGESTS.keys.join(', ')})"
+      end
+    end
+    private_class_method :sha_digest
+
     # Constant-time string comparison.
     def self.constant_time_equal?(a, b)
       return false if a.bytesize != b.bytesize
@@ -354,8 +479,10 @@ module Altcha
     # @param options [CreateChallengeOptions]
     # @return [Challenge]
     def self.create_challenge(options)
+      sha_digest(options.hmac_algorithm) # raise early, even for unsigned challenges
+      validate_counter_mode(options.counter_mode)
       key_length        = options.key_length        || DEFAULT_KEY_LENGTH
-      key_prefix        = options.key_prefix        || DEFAULT_KEY_PREFIX
+      key_prefix        = (options.key_prefix       || DEFAULT_KEY_PREFIX).downcase
       key_prefix_length = options.key_prefix_length || (key_length / 2)
       expires_at        = options.expires_at.is_a?(Time) ? options.expires_at.to_i : options.expires_at
 
@@ -377,21 +504,23 @@ module Altcha
       if options.counter
         nonce_bytes       = [parameters.nonce].pack('H*')
         salt_bytes        = [parameters.salt].pack('H*')
-        password_bytes    = make_password(nonce_bytes, options.counter)
+        password_bytes    = make_password(nonce_bytes, options.counter, options.counter_mode)
         derived_key_bytes = derive_key(parameters, salt_bytes, password_bytes)
         parameters.key_prefix = derived_key_bytes[0, key_prefix_length].unpack1('H*')
       end
 
-      if options.hmac_signature_secret
-        if derived_key_bytes && options.hmac_key_signature_secret
+      if js_truthy?(options.hmac_signature_secret)
+        if derived_key_bytes && js_truthy?(options.hmac_key_signature_secret)
           parameters.key_signature = hmac_hex(
             derived_key_bytes,
-            options.hmac_key_signature_secret
+            options.hmac_key_signature_secret,
+            options.hmac_algorithm
           )
         end
         signature = hmac_hex(
           canonical_json(parameters.to_h),
-          options.hmac_signature_secret
+          options.hmac_signature_secret,
+          options.hmac_algorithm
         )
         Challenge.new(parameters: parameters, signature: signature)
       else
@@ -404,19 +533,27 @@ module Altcha
     # @param max_counter [Integer, nil] Safety cap; nil means no limit.
     # @param counter_start [Integer]
     # @param counter_step [Integer]
-    # @return [Solution, nil]
-    def self.solve_challenge(challenge, max_counter: nil, counter_start: 0, counter_step: 1)
+    # @param counter_mode [String] 'uint32' (default) or 'string'; must match create_challenge.
+    # @param timeout [Numeric, nil] Milliseconds before giving up (default 90 000, as in JS);
+    #   nil or 0 disables it.
+    # @return [Solution, nil] nil when max_counter or the timeout is reached.
+    def self.solve_challenge(challenge, max_counter: nil, counter_start: 0, counter_step: 1,
+                             counter_mode: 'uint32', timeout: DEFAULT_SOLVE_TIMEOUT)
+      validate_counter_mode(counter_mode)
       parameters  = challenge.parameters
       nonce_bytes = [parameters.nonce].pack('H*')
       salt_bytes  = [parameters.salt].pack('H*')
-      key_prefix  = parameters.key_prefix
-      start_time  = Time.now
+      # Derived keys are lowercase hex; match prefixes case-insensitively.
+      key_prefix  = parameters.key_prefix.downcase
+      start_ms    = monotonic_ms
       counter     = counter_start
 
       loop do
         return nil if max_counter && counter > max_counter
+        # Checked every iteration (JS: every 10) since one KDF call can be slow.
+        return nil if timeout && timeout.positive? && monotonic_ms - start_ms > timeout
 
-        password_bytes    = make_password(nonce_bytes, counter)
+        password_bytes    = make_password(nonce_bytes, counter, counter_mode)
         derived_key_bytes = derive_key(parameters, salt_bytes, password_bytes)
         derived_key_hex   = derived_key_bytes.unpack1('H*')
 
@@ -424,7 +561,7 @@ module Altcha
           return Solution.new(
             counter:     counter,
             derived_key: derived_key_hex,
-            time:        ((Time.now - start_time) * 1000).round
+            time:        (monotonic_ms - start_ms).round
           )
         end
 
@@ -432,40 +569,62 @@ module Altcha
       end
     end
 
+    def self.monotonic_ms
+      Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
+    end
+    private_class_method :monotonic_ms
+
     # Verifies a v2 solution against its challenge.
     # @param challenge [Challenge]
     # @param solution [Solution]
     # @param hmac_signature_secret [String] Must match what was used in create_challenge.
     # @param hmac_key_signature_secret [String, nil] Required when keySignature is present.
     # @param hmac_algorithm [String] Defaults to 'SHA-256'.
+    # @param counter_mode [String] 'uint32' (default) or 'string'; must match create_challenge.
     # @return [VerifySolutionResult]
     def self.verify_solution(challenge, solution, hmac_signature_secret:,
                              hmac_key_signature_secret: nil,
-                             hmac_algorithm: 'SHA-256')
+                             hmac_algorithm: 'SHA-256', counter_mode: 'uint32')
       start_time = Time.now
-
-      # 1. Expiration check.
-      if challenge.parameters.expires_at && Time.now.to_i > challenge.parameters.expires_at
+      sha_digest(hmac_algorithm) # raise on misconfiguration, before any early return
+      validate_counter_mode(counter_mode)
+      # An empty secret makes signatures forgeable (JS WebCrypto rejects it too).
+      raise ArgumentError, 'hmac_signature_secret must be a non-empty String' unless js_truthy?(hmac_signature_secret)
+
+      # 1. Expiration check. Runs before the signature check, so expires_at may
+      # be tampered: only numbers are compared; anything else falls through and
+      # fails the signature check. Like JS `expiresAt && expiresAt < now`:
+      # 0 means no expiry, and now keeps fractional seconds (no 1 s grace).
+      expires_at = challenge.parameters.expires_at
+      if (expires_at.is_a?(Integer) || expires_at.is_a?(Float)) &&
+         !expires_at.zero? && expires_at < Time.now.to_f
         return VerifySolutionResult.new(
           expired: true, invalid_signature: nil, invalid_solution: nil,
           time: elapsed_ms(start_time), verified: false
         )
       end
 
-      # 2. Signature presence check.
-      unless challenge.signature
+      # 2. Signature presence check. The signature is client input: anything
+      # but a String (e.g. 123, an Array) is invalid instead of raising.
+      unless challenge.signature.is_a?(String)
         return VerifySolutionResult.new(
           expired: false, invalid_signature: true, invalid_solution: nil,
           time: elapsed_ms(start_time), verified: false
         )
       end
 
-      # 3. Verify challenge signature (tamper detection).
-      expected_sig = hmac_hex(
-        canonical_json(challenge.parameters.to_h),
-        hmac_signature_secret,
-        hmac_algorithm
-      )
+      # 3. Verify challenge signature (tamper detection). The parameters are
+      # client input: strings that cannot be serialized (invalid UTF-8, e.g. a
+      # JSON-parsed lone surrogate) cannot match any signature we issued.
+      begin
+        signed_json = canonical_json(challenge.parameters.to_h)
+      rescue JSON::GeneratorError, EncodingError
+        return VerifySolutionResult.new(
+          expired: false, invalid_signature: true, invalid_solution: nil,
+          time: elapsed_ms(start_time), verified: false
+        )
+      end
+      expected_sig = hmac_hex(signed_json, hmac_signature_secret, hmac_algorithm)
       unless constant_time_equal?(challenge.signature, expected_sig)
         return VerifySolutionResult.new(
           expired: false, invalid_signature: true, invalid_solution: nil,
@@ -473,11 +632,25 @@ module Altcha
         )
       end
 
+      # The solution is unsigned client input: reject malformed fields instead
+      # of raising. Counter must be a JSON number (in uint32 mode a whole number
+      # in 0..2^32-1, so each solution has one counter); derived_key must be a string.
+      unless valid_solution_fields?(solution, counter_mode)
+        return VerifySolutionResult.new(
+          expired: false, invalid_signature: false, invalid_solution: true,
+          time: elapsed_ms(start_time), verified: false
+        )
+      end
+
       # 4a. Fast path: verify via key signature when available.
-      if challenge.parameters.key_signature && hmac_key_signature_secret
-        derived_key_bytes = [solution.derived_key].pack('H*')
-        expected_key_sig  = hmac_hex(derived_key_bytes, hmac_key_signature_secret, hmac_algorithm)
-        valid = constant_time_equal?(challenge.parameters.key_signature, expected_key_sig)
+      # pack('H*') never fails: it pads odd lengths and maps non-hex characters
+      # to nibbles, so only well-formed hex is decoded.
+      if js_truthy?(challenge.parameters.key_signature) && js_truthy?(hmac_key_signature_secret)
+        valid = HEX_PATTERN.match?(solution.derived_key) &&
+                constant_time_equal?(
+                  challenge.parameters.key_signature,
+                  hmac_hex([solution.derived_key].pack('H*'), hmac_key_signature_secret, hmac_algorithm)
+                )
         return VerifySolutionResult.new(
           expired: false, invalid_signature: false, invalid_solution: !valid,
           time: elapsed_ms(start_time), verified: valid
@@ -488,11 +661,11 @@ module Altcha
       # and require it to satisfy the signed key prefix.
       nonce_bytes       = [challenge.parameters.nonce].pack('H*')
       salt_bytes        = [challenge.parameters.salt].pack('H*')
-      password_bytes    = make_password(nonce_bytes, solution.counter)
+      password_bytes    = make_password(nonce_bytes, solution.counter, counter_mode)
       derived_key_bytes = derive_key(challenge.parameters, salt_bytes, password_bytes)
       derived_key_hex   = derived_key_bytes.unpack1('H*')
       key_matches       = constant_time_equal?(derived_key_hex, solution.derived_key)
-      prefix_matches    = derived_key_hex.start_with?(challenge.parameters.key_prefix)
+      prefix_matches    = derived_key_hex.start_with?(challenge.parameters.key_prefix.downcase)
       invalid           = !(key_matches && prefix_matches)
 
       VerifySolutionResult.new(
@@ -526,19 +699,17 @@ module Altcha
       nil
     end
 
-    # Verifies the SHA hash of selected form fields.
+    # Verifies the SHA hash of selected form fields. Like JS
+    # `String(data[field] || '')`, falsy values (nil, false, 0, '') hash as ''.
     # @param form_data [Hash]
     # @param fields [Array<String>]
     # @param fields_hash [String] Expected hex digest.
-    # @param algorithm [String] Defaults to 'SHA-256'.
+    # @param algorithm [String] 'SHA-256' (default), 'SHA-384' or 'SHA-512';
+    #   anything else raises ArgumentError (JS crypto.subtle.digest throws).
     # @return [Boolean]
     def self.verify_fields_hash(form_data:, fields:, fields_hash:, algorithm: 'SHA-256')
-      digest = case algorithm
-               when 'SHA-512' then 'SHA512'
-               when 'SHA-384' then 'SHA384'
-               else 'SHA256'
-               end
-      lines = fields.map { |f| form_data[f].to_s }
+      digest = sha_digest(algorithm)
+      lines = fields.map { |f| js_truthy?(form_data[f]) ? form_data[f].to_s : '' }
       OpenSSL::Digest.hexdigest(digest, lines.join("\n")) == fields_hash
     end
 
@@ -549,21 +720,19 @@ module Altcha
     def self.verify_server_signature(payload:, hmac_secret:)
       start_time = Time.now
 
-      digest = case payload.algorithm
-               when 'SHA-512' then 'SHA512'
-               when 'SHA-384' then 'SHA384'
-               else 'SHA256'
-               end
-
-      hash_bytes        = OpenSSL::Digest.digest(digest, payload.verification_data)
-      expected_sig      = hmac_hex(hash_bytes, hmac_secret, payload.algorithm)
+      # The payload is client input: an unsupported algorithm or non-String
+      # verification_data fails the signature check instead of raising.
+      digest = SHA_DIGESTS[payload.algorithm] if payload.verification_data.is_a?(String)
+      expected_sig = if digest
+                       hmac_hex(OpenSSL::Digest.digest(digest, payload.verification_data), hmac_secret, payload.algorithm)
+                     end
       verification_data = parse_verification_data(payload.verification_data)
 
-      expired = !!(verification_data &&
-                   verification_data['expire'] &&
-                   verification_data['expire'] < Time.now.to_i)
+      # Like JS `!!expire && expire < now`: non-numeric or 0 never expires.
+      expire  = verification_data && verification_data['expire']
+      expired = (expire.is_a?(Integer) || expire.is_a?(Float)) && !expire.zero? && expire < Time.now.to_i
 
-      invalid_signature = !constant_time_equal?(payload.signature.to_s, expected_sig)
+      invalid_signature = expected_sig.nil? || !constant_time_equal?(payload.signature.to_s, expected_sig)
 
       invalid_solution = verification_data.nil? ||
                          verification_data['verified'] != true ||
@@ -584,6 +753,33 @@ module Altcha
     def self.elapsed_ms(start_time)
       ((Time.now - start_time) * 1000).round
     end
+
+    # derived_key must be a validly encoded String: the 4a hex regex raises on
+    # invalid UTF-8, and such a key can never match a hex key in 4b.
+    # In uint32 mode the counter must be a whole number in 0..MAX_UINT32: JS
+    # wraps larger values (and rounds them above 2^53), so they would only be
+    # aliases of a smaller counter. Stricter than JS, which accepts c + 2^32.
+    def self.valid_solution_fields?(solution, counter_mode)
+      counter     = solution.counter
+      derived_key = solution.derived_key
+      valid_counter = if counter_mode == 'uint32'
+                        (counter.is_a?(Integer) || (counter.is_a?(Float) && counter.finite? && counter % 1 == 0)) &&
+                          counter >= 0 && counter <= MAX_UINT32
+                      else
+                        counter.is_a?(Integer) || (counter.is_a?(Float) && counter.finite?)
+                      end
+      valid_counter && derived_key.is_a?(String) && derived_key.valid_encoding?
+    end
+    private_class_method :valid_solution_fields?
+
+    # JS truthiness: nil, false, '', 0, -0.0 and NaN are falsy.
+    def self.js_truthy?(value)
+      return false if value.nil? || value == false || value == ''
+      return !(value.zero? || (value.is_a?(Float) && value.nan?)) if value.is_a?(Numeric)
+
+      true
+    end
+    private_class_method :js_truthy?
     private_class_method :elapsed_ms
   end
 end

data/lib/altcha/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Altcha
-  VERSION = '2.0.1'
+  VERSION = '3.0.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: altcha
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 3.0.0
 platform: ruby
 authors:
 - Daniel Regeci
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-30 00:00:00.000000000 Z
+date: 2026-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: argon2-kdf
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -77,6 +91,7 @@ files:
 - ".github/workflows/publish.yml"
 - ".gitignore"
 - ".rspec"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
 - Gemfile
@@ -105,7 +120,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="