Credential Stuffing in Hanami with Hmac Signatures

Credential stuffing relies on automated login attempts using breached username and password pairs. In Hanami applications that use Hmac Signatures to authenticate requests, a common misconfiguration can weaken the protection these signatures provide and expose an authentication bypass or credential‑stuffing surface.

Hmac Signatures typically bind a request payload, method, and timestamp to a secret key, producing a signature sent in a header. If the application validates the signature but does not sufficiently bind the signature to the authentication context (for example, the user identity or session), an attacker can replay a valid signature obtained from a different source or reuse a captured request while substituting the authentication target. In Hanami, this can happen when the signature is computed without including a per‑user secret or a nonce, or when the server uses a global shared secret without tying it to a specific user credential. An attacker performing credential stuffing can iterate over known username and password pairs, observe whether the Hmac‑protected login request succeeds or fails differently, and infer valid credentials based on signature acceptance behavior or timing differences.

Additionally, if the Hanami application exposes an unauthenticated endpoint that accepts Hmac‑signed requests and does not enforce rate limiting or request uniqueness, attackers can automate large volumes of login attempts while reusing valid signatures for known payloads. The lack of per‑request nonces or replay protection can allow the same signed request to be replayed across multiple accounts during a credential‑stuffing campaign. Because Hmac Signatures ensure integrity and authenticity of a request but do not inherently prevent replay unless explicitly designed to do so, the combination with weak identity binding and missing account lockout or anomaly detection increases the risk of successful credential stuffing.

Another specific risk arises when the Hanami backend processes Hmac‑signed JSON payloads that include user-supplied identifiers (such as email or username) but does not validate those identifiers against the signature context. An attacker can submit a Hmac‑signed request with a guessed username and a valid signature generated for a different username, and if the server trusts the payload content over the signature binding, it may inadvertently authenticate the wrong account. This illustrates why the signature must cover the exact identity claim and why the application must correlate the signature verification with the authentication step rather than treating them as independent checks.

To mitigate credential stuffing risks when using Hmac Signatures in Hanami, ensure that the signature scope tightly binds to the user identity and includes anti‑replay controls. Below are concrete code examples that demonstrate a safer approach.

Include user-specific secret and nonce in the signature

Instead of using a global shared secret, derive a per‑user secret (for example, from a user’s API key or password hash) and include a server‑generated nonce or timestamp in the signed payload. This prevents signature reuse across accounts and limits the usefulness of captured requests.

require "openssl"
require "base64"
require "json"

module HmacAuth
  extend self

  def generate_signature(user_secret, payload_body, http_method, timestamp)
    data = "#{timestamp}:#{http_method}:#{payload_body}"
    OpenSSL::HMAC.hexdigest("sha256", user_secret, data)
  end

  def verify_signature(user_secret, payload_body, http_method, timestamp, received_signature, allowed_skew = 300)
    now = Time.now.to_i
    return false if (now - timestamp).abs > allowed_skew
    expected = generate_signature(user_secret, payload_body, http_method, timestamp)
    ActiveSupport::SecurityUtils.secure_compare(expected, received_signature)
  end
end

In your Hanami controller, compute the user secret from a stored key (never send the raw secret to the client) and validate the nonce/timestamp before processing the request.

class Api::V1::SessionsController < Hanami::Action
  def create
    timestamp = request.headers["X-Request-Timestamp"]&.to_i
    nonce     = request.headers["X-Nonce"]
    signature = request.headers["X-Signature"]
    user      = UserRepository.find_by(email: params[:email])

    unless user && timestamp && nonce && signature
      halt 400, { error: "missing parameters" }.to_json
    end

    # Prevent replay: ensure nonce was not used recently (pseudocode)
    if NonceStore.replayed?(nonce)
      halt 401, { error: "replay detected" }.to_json
    end

    user_secret = user.api_secret # stored securely, e.g., hashed
    payload_body = request.body.read
    request.body.rewind

    if HmacAuth.verify_signature(user_secret, payload_body, request.request_method, timestamp, signature)
      # Bind authentication to the user identified by the payload, not only by signature validity
      if user.email == params[:email]
        session[:user_id] = user.id
        NonceStore.record(nonce)
        Response::Ok.render("login success")
      else
        halt 401, { error: "identity mismatch" }.to_json
      end
    else
      halt 401, { error: "invalid signature" }.to_json
    end
  end
end

Enforce replay protection and rate limiting at the application and gateway level

Even with per‑user secrets, implement replay protection by storing recently used nonces or request identifiers for a short window. Combine this with rate limiting on login endpoints to reduce the effectiveness of credential stuffing.

# Example nonce store with TTL (pseudocode, adapt to your storage)
module NonceStore
  def self.record(nonce)
    redis.setex("nonce:#{nonce}", 300, "used")
  end

  def self.replayed?(nonce)
    redis.setnx("nonce:#{nonce}", "used") == 0
  end
end

Ensure that your Hmac signature verification occurs after basic input validation and that the identity claim in the payload is cross‑checked against the authenticated user. This prevents an attacker from swapping usernames while relying on a valid Hmac signature generated for a different identity.