Class: Faraday::HttpSignature::Middleware

Inherits:

Middleware

• Object
• Middleware
• Faraday::HttpSignature::Middleware

Defined in:

lib/faraday/http_signature/middleware.rb

Overview

Faraday middleware for HTTP message signing and verification (RFC 9421).

When registered via request, signs outgoing requests (default). When registered via response, verifies incoming response signatures. When registered via use, signs requests by default; pass verify_response: true to also verify responses.

Verification result metadata

After response verification, the middleware stores results in env[:http_signature_verified] (true or false) and env[:http_signature] (the Linzer::Signature on success). These are accessible via response.env[:http_signature_verified].

Examples:

Sign requests

conn = Faraday.new(url: "https://example.com") do |f|
  f.request :http_signature, key: my_key, components: %w[@method @path]
end

Verify responses

conn = Faraday.new(url: "https://example.com") do |f|
  f.response :http_signature, verify_key: server_pubkey
end

Lenient verification (no exception on failure)

conn = Faraday.new(url: "https://example.com") do |f|
  f.response :http_signature, verify_key: server_pubkey, strict: false
end
response = conn.get("/")
response.env[:http_signature_verified]  # => true or false

See Also:

• RFC 9421

Direct Known Subclasses

Request, Response

Defined Under Namespace

Classes: Options, Request, Response

Constant Summary

DEFAULT_OPTIONS =

Default options for the base middleware class (used by use and request registrations). Signs requests, does not verify responses, strict mode enabled.

{
  sign_request:    true,
  verify_response: false,
  strict:          true
}.freeze

Instance Method Summary

• #initialize(app, options = nil) ⇒ Middleware constructor

  Creates a new middleware instance.

• #on_complete(env) ⇒ Faraday::Env^?

  Verifies the response signature when Options#verify_response? is true.

• #on_request(env) ⇒ Faraday::Env^?

  Signs the outgoing request when Options#sign_request? is true.

Constructor Details

#initialize(app, options = nil) ⇒ Middleware

Creates a new middleware instance.

Merges class-level DEFAULT_OPTIONS with the user-provided options so that subclasses (Request, Response) can override defaults.

Parameters:

• app (#call) —

  the next middleware or adapter in the stack

• options (Hash, nil) (defaults to: nil) —

  middleware options

Options Hash (options):

• :key (Linzer::Key) —

  generic key for signing or verification

• :sign_key (Linzer::Key) —

  explicit signing key

• :verify_key (Linzer::Key) —

  explicit verification key

• :components (Array<String>) —

  components to sign

• :params (Hash) —

  additional signature parameters

• :sign_request (Boolean) — default: +true+ —

  whether to sign requests

• :verify_response (Boolean) — default: +false+ —

  whether to verify responses

• :strict (Boolean) — default: +true+ —

  raise on verification failure

# File 'lib/faraday/http_signature/middleware.rb', line 182

def initialize(app, options = nil)
  super(app)
  defaults = self.class::DEFAULT_OPTIONS
  merged = defaults.merge(Hash(options))
  @options = Options.from(merged)
end

Instance Method Details

#on_complete(env) ⇒ Faraday::Env^?

Verifies the response signature when Faraday::HttpSignature::Middleware::Options#verify_response? is true.

On success, sets env[:http_signature_verified] to true and env[:http_signature] to the verified Linzer::Signature.

On failure in strict mode (default), raises VerifyError. In lenient mode (+strict: false+), sets env[:http_signature_verified] to false and allows the response to continue through the middleware stack.

Parameters:

• env (Faraday::Env) —

  the middleware environment

Returns:

• (Faraday::Env, nil) —

  the modified env, or nil if verifying is disabled

Raises:

• (VerifyError) —

  if verification fails and strict is true

• (Linzer::Error) —

  if no valid verification key is available

# File 'lib/faraday/http_signature/middleware.rb', line 234

def on_complete(env)
  env[:http_signature_verified] = false
  return unless options.verify_response?

  key = resolve_verify_key
  response = ::Faraday::Response.new(env)
  message = Linzer::Message.new(response)
  signature = Linzer::Signature.build(response.headers)

  Linzer.verify(key, message, signature)
  env[:http_signature_verified] = true
  env[:http_signature] = signature
  env
rescue Linzer::Error => e
  raise VerifyError.new(e, response: response) if options.strict?
end

#on_request(env) ⇒ Faraday::Env^?

Signs the outgoing request when Faraday::HttpSignature::Middleware::Options#sign_request? is true.

Resolves the signing key, builds a Linzer::Message from the Faraday environment, generates a signature over the configured components, and merges the signature and signature-input headers into the request.

Parameters:

• env (Faraday::Env) —

  the middleware environment

Returns:

• (Faraday::Env, nil) —

  the modified env, or nil if signing is disabled

Raises:

• (Linzer::Error) —

  if no valid signing key is available

# File 'lib/faraday/http_signature/middleware.rb', line 200

def on_request(env)
  return unless options.sign_request?

  key = resolve_signing_key
  request = Linzer::Faraday::Utils.create_request(env)

  Linzer.sign! request,
               key:        key,
               components: options.components,
               params:     options.params,
               profile:    options.profile

  signature_headers = request.headers.slice("signature", "signature-input")
  env.request_headers.merge!(signature_headers)
  env
rescue Linzer::Error => e
  raise SigningError, e if options.strict?
end