Identification Failures in Hanami with Hmac Signatures

Identification failures occur when an application cannot reliably establish or verify the identity of a request originator. In Hanami, using Hmac Signatures for request authentication can inadvertently create or expose identification weaknesses if the signature is computed over incomplete or mutable data, or if the server-side verification logic does not consistently bind the signature to a specific identifier (e.g., an API key ID and the exact request payload). For example, if the client computes the HMAC over the request body and a set of headers but the server recomputes it using a different subset of headers or a normalized body that differs subtly (such as different ordering of JSON keys or omitted fields), the same request may produce different digests. This mismatch leads to failed authentication that may be misinterpreted as an invalid signature rather than a faulty identification path, and may cause the server to reject valid requests or, worse, accept requests when fallback or lenient verification is used.

In Hanami, Hmac Signatures are typically implemented by having the client include a hash-based message authentication code—generated with a shared secret—alongside headers that identify the signing scope (e.g., timestamp, nonce, and selected headers). If the server does not enforce strict canonicalization, an attacker can exploit inconsistencies between client and server interpretation to bypass identification checks. Consider a scenario where the client signs a JSON payload and the server only hashes selected headers without ensuring deterministic key ordering; an attacker could alter non-critical headers or body fields, causing the server to compute a different HMAC yet still route the request through a weaker identification path. This can lead to privilege confusion or allow an attacker to reuse a signed request intended for one resource against another resource that uses the same verification logic but different authorization context, effectively bypassing intended identification boundaries.

Another dimension involves how Hanami applications integrate Hmac Signatures with routing and controller lookup. If the identifier used to locate the endpoint or tenant is derived from a header that is not part of the signed data, an attacker can manipulate that header to redirect the request to a different internal handler while presenting a valid signature. Because the signature validates the content and selected headers but not the routing identifier, the application may incorrectly attribute the request to a different client or service, resulting in identification failure. This is especially risky when combined with mass assignment or parameter pollution in the controller, where the server may inadvertently trust user-supplied values for identification after signature verification.

The risk is compounded when applications use time-sensitive components like timestamps and nonces without strict validation windows and replay protection. Without a tight bound on acceptable time drift and without tracking used nonces, an attacker can replay a valid Hmac-signed request within the allowed window, and the server may treat it as a new, legitimate identification event. In Hanami, this can lead to duplicate operations or unauthorized access when the signature is valid but the identification context (e.g., session or scope) has changed. Therefore, identification failures with Hmac Signatures in Hanami stem from inconsistent canonicalization, incomplete signature scope, and weak binding between the signature and the routing/authorization identifiers.

To remediate identification failures when using Hmac Signatures in Hanami, ensure that the server and client share a strict canonicalization strategy and that the signature covers all components that influence identification and authorization. The following examples demonstrate a robust approach using a standard HMAC-SHA256 scheme with explicit header inclusion, timestamp, and nonce handling.

First, define a shared secret and a helper to compute and verify the signature. Use a deterministic method to serialize the data to be signed, such as concatenating selected header values and the raw request body in a predefined order.

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

module HmacUtils
  SHARED_SECRET = ENV.fetch("HMAC_SHARED_SECRET")

  def self.compute_signature(headers, body)
    # Canonicalize: include timestamp, nonce, and specific headers in fixed order
    timestamp = headers["X-Timestamp"]
    nonce     = headers["X-Nonce"]
    selected  = headers["X-Client-Id"]
    message   = [timestamp, nonce, selected, body].join("|")
    OpenSSL::HMAC.hexdigest("SHA256", SHARED_SECRET, message)
  end

  def self.valid_signature?(headers, body, received_signature)
    computed = compute_signature(headers, body)
    secure_compare(computed, received_signature)
  end

  def self.secure_compare(a, b)
    return false unless a.bytesize == b.bytesize
    l = a.unpack "C#{a.bytesize}"
    res = 0
    b.each_byte { |byte| res |= byte ^ l.shift }
    res == 0
  end
end

On the client side, construct the request by adding the required headers and computing the Hmac over the same canonical string.

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

headers = {
  "X-Timestamp"     => Time.now.utc.iso8601,
  "X-Nonce"         => SecureRandom.uuid,
  "X-Client-Id"     => "my-client-id",
  "Content-Type"    => "application/json"
}
body = { action: "transfer", amount: 100, currency: "USD" }.to_json
message = [headers["X-Timestamp"], headers["X-Nonce"], headers["X-Client-Id"], body].join("|")
signature = OpenSSL::HMAC.hexdigest("SHA256", ENV.fetch("HMAC_SHARED_SECRET"), message)

request = Net::HTTP::Post.new("/api/v1/transactions")
headers.each { |k, v| request[k] = v }
request["X-Signature"] = signature
request.body = body

response = Net::HTTP.start("api.example.com") { |http| http.request(request) }

On the Hanami server side, in your endpoint or middleware, verify the signature and ensure the identifiers are validated before proceeding with business logic.

class Api::BaseRoute < Hanami::Action
  def call(params)
    headers = env["rack.request.headers"]
    body    = env["rack.input"].read
    env["rack.input"] = StringIO.new(body) # rewind for downstream use

    received_signature = headers["X-Signature"]
    unless HmacUtils.valid_signature?(headers, body, received_signature)
      halt 401, { error: "invalid_signature" }.to_json
    end

    # Ensure the identifiers used for lookup are derived from signed headers
    client_id = headers["X-Client-Id"]
    timestamp = headers["X-Timestamp"]
    # Reject stale requests (e.g., more than 300 seconds old)
    unless within_time_window?(timestamp, acceptable_seconds: 300)
      halt 401, { error: "stale_timestamp" }.to_json
    end

    # Proceed with identification and authorization using client_id
    @current_account = AccountRepository.find_by_external_id(client_id)
    halt 404, { error: "not_found" }.to_json unless @current_account

    @response.status = 200
    @response
  end

  private

  def within_time_window?(timestamp, acceptable_seconds: 300)
    request_time = Time.iso8601(timestamp)
    (Time.now - request_time).abs <= acceptable_seconds
  end
end

These snippets enforce a strict binding between the signature, the client identifier, and the temporal validity of the request, reducing the surface for identification failures. Always include the routing identifier (e.g., client ID) inside the signed scope and avoid deriving it from unsigned headers. Additionally, enforce replay protection by tracking nonces or using short timestamp windows, and ensure consistent JSON key ordering and header casing on both sides to avoid subtle canonicalization differences that lead to identification mismatches.