Insecure Design in Hanami with Mutual Tls

Insecure design in a Hanami application combined with mutual TLS (mTLS) can undermine the security that transport-layer encryption is meant to provide. Hanami encourages a modular architecture where service objects, repositories, and controllers are composed explicitly. When mTLS is introduced, developers may assume that authenticated client certificates alone are sufficient to protect sensitive operations, leading to design decisions that skip authorization checks at the application layer.

For example, a Hanami endpoint that uses mTLS might verify the presence of a client certificate but then rely on the identity derived from the certificate (e.g., a subject or serial number) to directly perform actions such as modifying records or escalating privileges. This is an insecure design pattern because identity does not equal authorization. Without explicit policy checks, an attacker who compromises a valid certificate or tricks a user into installing a malicious certificate can perform actions across the system according to the permissions associated with that certificate.

Another specific risk arises when mTLS is configured at the reverse proxy or load balancer rather than within the Hanami application. In such setups, the application may trust headers like X-SSL-Client-Verify or X-SSL-Client-Cert without robust validation. An insecure design that does not verify the certificate chain against a trusted CA, enforce revocation checks, or bind certificate identities to application-level roles can allow unauthorized requests to appear legitimate. This is especially dangerous when combined with broad permissions granted to certificate subject names, echoing patterns seen in BOLA/IDOR when object-level ownership is not validated.

Input validation and property authorization also intersect poorly with an insecure mTLS design. If a Hanami service accepts parameters that influence database queries and these parameters are not validated against the authenticated client’s certificate-based identity, attackers may manipulate inputs to access or modify resources owned by other clients. This mirrors BFLA and privilege escalation risks: the system mistakenly assumes that mTLS provides sufficient isolation, leading to missing checks on object ownership or tenant boundaries.

LLM/AI security considerations emerge when mTLS-protected endpoints expose generated artifacts or logs containing certificate metadata. If Hanami responses inadvertently expose certificate details or stack traces, output scanning may reveal sensitive information. Moreover, if the application automatically trusts mTLS client identities in contexts used by AI-assisted tooling (e.g., code generation or API discovery), it may expose system prompt leakage patterns or enable prompt injection through misconfigured endpoints that should have required additional verification beyond mTLS.

Finally, data exposure and encryption design can be misaligned with mTLS. Relying solely on mTLS for confidentiality without encrypting sensitive fields at rest or ensuring proper key management may violate data exposure controls. If Hanami logs or caches contain client certificate information without protection, these stores become high-value targets. Ensuring that mTLS is part of a layered security design that includes encryption, strict identity-to-role mapping, and continuous monitoring is essential to avoid insecure patterns that expose the attack surface.

To remediate insecure design issues when using mutual TLS in Hanami, explicitly enforce authorization checks and validate certificate metadata within application code rather than relying on transport-layer assumptions. Below are concrete code examples demonstrating secure patterns.

First, configure Hanami to require client certificates and extract verified identity information in a centralized point, such as a rack middleware or a base action class. This ensures every request validates the certificate chain and maps it to an application subject before reaching business logic.

# config/initializers/mtls.rb
require 'openssl'

class MtlsValidator
  def initialize(app)
    @app = app
    @ca = OpenSSL::X509::Certificate.new(File.read(Rails.root.join('certs/ca.pem')))
  end

  def call(env)
    cert_der = env['SSL_CLIENT_CERT']
    if cert_der.nil? || cert_der.empty?
      return [403, { 'Content-Type' => 'application/json' }, [{ error: 'client certificate required' }.to_json]]
    end

    cert = OpenSSL::X509::Certificate.new(cert_der)
    store = OpenSSL::X509::Store.new
    store.add_cert(@ca)
    store.verify(cert) || raise('Client certificate invalid')

    # Map certificate subject to application user/role
    subject = cert.subject.to_s
    identity = extract_identity(subject)
    env['hanami.identity'] = identity
    @app.call(env)
  rescue OpenSSL::X509::StoreError
    return [403, { 'Content-Type' => 'application/json' }, [{ error: 'certificate verification failed' }.to_json]]
  end

  private

  def extract_identity(subject)
    # Example: /CN=alice/O=acme
    matches = subject.match(%r{/CN=([^/]+)/O=([^/]+)})
    return nil unless matches
    { username: matches[1], organization: matches[2] }
  end
end

Rack::Builder.new do
    use MtlsValidator
    run Hanami::Kernel.new
end

Second, in your Hanami actions, always perform object-level authorization using the mapped identity instead of trusting certificate-derived roles implicitly. For example, when updating a resource, verify ownership or role-based access control (RBAC) attributes stored in your domain layer.

# actions/articles/update.rb
class Articles::Update
  include Hanami::Action

  def handle_request
    # identity injected by MIDDLEWARE
    identity = env['hanami.identity'] || raise('identity missing')
    article = ArticleRepository.new.find(params[:id])
    raise Hanami::Action::Forbidden unless article.owned_by?(identity[:username])

    article.update(title: params[:title], body: params[:body])
    Response::Ok.render(article: article)
  end
end

Third, if your deployment terminates mTLS at a proxy, ensure the Hanami application validates the proxy headers against strict allowlists and does not accept them blindly. Treat these headers as untrusted unless verified by an upstream authenticator.

# config/initializers/trusted_proxy_headers.rb
# Only enable if mTLS is terminated upstream and headers are injected by a trusted proxy
ALLOWED_PROXY_HEADERS = %w[X-SSL-Client-Verify X-SSL-Client-Cert].freeze

def verify_proxy_headers(headers)
  raise 'Missing client certificate header' unless headers['X-SSL-Client-Verify'] == 'SUCCESS'
  cert_b64 = headers['X-SSL-Client-Cert']
  # Re-validate in app if needed, or map to identity via a trusted lookup
end

Finally, integrate mTLS checks into your CI/CD pipeline using the middlebrick CLI to scan your API endpoints and confirm that mTLS configurations are correctly enforced and that no endpoints rely solely on transport-layer authentication. Use the dashboard to track security scores over time and the GitHub Action to fail builds if risk thresholds are exceeded.