mailkube 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7641c72078cd5550384c2e708dc156aea1f487d2304d07689ed7fcebc0868bd4
-  data.tar.gz: 4d0d9ea1e793297301d4cc7652a3ee0fa40b08dc7fcc2fa069b33cb20ddcfef2
+  metadata.gz: 62f56b63852a247583a1bbb34cbe7f816ecfdfcbbaf672281b1e4396a697c8e7
+  data.tar.gz: c12d752ba809c48b7d7cf6d1cade536b839be61279d2109d2320c96ee187c3bb
 SHA512:
-  metadata.gz: 8abad977f64add055a7d30eb83c88529ba3602fdeeb37f7f543386f2b7683fbec70e00f28e7cd102fa1288fabf4f503dbf81cf4c616429f62539d672c3c2b499
-  data.tar.gz: dd85a8fc81e7cc52a2446bd13e70a348866694b65c0034133b4dbfe7fe8ecd31c45f82a4479216e60d783785131a5d5a27fa90ce265d86c3949493f161191cc2
+  metadata.gz: 3dd9768193d7ca0a700cdb6d6af906ddb33533adc9182de122be1debb9617cf000899b0102e396549cf55c19e1c3df26ec9d6cf8f94d8b15f676fcede3841f9b
+  data.tar.gz: b5daed405e91f130357dd2a65e5e03284f5616d2676ce6b0d4eb53adff715a004f07594d6e70d051aa9681e1fe8aebbfff4da0f477222a99307cbd2fff900f3b

data/README.md

@@ -46,6 +46,13 @@ Create one client and reuse it.
 | Base URL | `base_url:` | `MAILKUBE_BASE_URL` | `https://api.mailkube.com/mta/v1/` |
 | Timeout | `timeout:` | | 30s |
 | HTTP adapter | `http:` | | `Mailkube::NetHttpAdapter` |
+| User-Agent suffix | `user_agent_suffix:` | | none |
+
+If you are building something on top of this gem — a CLI, an internal service, a framework
+integration — set `user_agent_suffix:` to your own `name/version`. It is appended after this SDK's
+own token, so both are visible: `mailkube-ruby/1.1.0 my-cli/1.0.0`. Surrounding whitespace is
+trimmed, and a value containing CR or LF is **ignored rather than sanitized** — a header value that
+could split the request is not one this gem will send, and quietly repairing it would hide the bug.
 
 Pass your own `http:` adapter — anything responding to
 `#call(method:, url:, headers:, body:)` and returning a `Mailkube::HttpResponse` — to route
@@ -198,6 +205,15 @@ header mapping, including Rack's CGI-env spelling.
 `Mailkube::Webhooks.verify_signature` is the signature check alone, if you want to parse yourself.
 `X-Webhook-Id` is stable across retries; deduplicate on it.
 
+`Mailkube::Webhooks.sign` is the mirror, so your own tests can build a valid request without
+reimplementing the HMAC from this page:
+
+```ruby
+signature = Mailkube::Webhooks.sign(
+  id: "wh_1", timestamp: Time.now.utc.iso8601, payload: body, secret: secret
+)
+```
+
 ### Endpoint registration
 
 When you create an endpoint, or re-point an existing one, mailkube probes it with

data/lib/mailkube/client.rb

@@ -35,9 +35,15 @@ module Mailkube
     # @param http [#call, nil] an HTTP adapter to use instead of the built-in {NetHttpAdapter}.
     #   This is the dependency-inversion seam the test suite injects through; when supplied,
     #   `timeout` is the adapter's business rather than this client's.
+    # @param user_agent_suffix [String, nil] a `name/version` token identifying software that
+    #   wraps this SDK — a CLI, an internal service, a framework integration — appended after
+    #   this SDK's own token so both are visible. A value containing CR or LF is ignored.
     # @raise [ConfigurationError] when no API key is available.
-    def initialize(api_key: nil, base_url: nil, timeout: Config::DEFAULT_TIMEOUT, http: nil)
-      config = Config.new(api_key: api_key, base_url: base_url, timeout: timeout)
+    def initialize(api_key: nil, base_url: nil, timeout: Config::DEFAULT_TIMEOUT, http: nil,
+                   user_agent_suffix: nil)
+      config = Config.new(
+        api_key: api_key, base_url: base_url, timeout: timeout, user_agent_suffix: user_agent_suffix
+      )
       transport = Transport.new(config, http || NetHttpAdapter.new(timeout: timeout))
 
       @config = config

data/lib/mailkube/config.rb

@@ -30,14 +30,20 @@ module Mailkube
     # @param api_key [String, nil] the API key; falls back to `MAILKUBE_API_KEY`.
     # @param base_url [String, nil] the API base URL; falls back to `MAILKUBE_BASE_URL`.
     # @param timeout [Integer, Float] the per-request timeout in seconds.
+    # @param user_agent_suffix [String, nil] a `name/version` token identifying software that
+    #   wraps this SDK, appended after this SDK's own token.
     # @raise [ConfigurationError] when no API key is available.
-    def initialize(api_key: nil, base_url: nil, timeout: DEFAULT_TIMEOUT)
+    def initialize(api_key: nil, base_url: nil, timeout: DEFAULT_TIMEOUT, user_agent_suffix: nil)
       key = api_key || ENV.fetch(ENV_API_KEY, nil)
       raise ConfigurationError, "no API key provided: pass api_key: or set #{ENV_API_KEY}" if key.nil? || key.empty?
 
       @api_key = key
       @base_url = base_url || ENV.fetch(ENV_BASE_URL, nil) || Mailkube::DEFAULT_BASE_URL
       @timeout = timeout
+      suffix = user_agent_suffix.to_s.strip
+      # Dropped rather than sanitized: a header value that could split the request is not one this
+      # gem will send, and silently repairing it hides the caller's bug.
+      @user_agent_suffix = suffix.match?(/[\r\n]/) ? "" : suffix
       freeze
     end
 
@@ -51,12 +57,23 @@ module Mailkube
     def default_headers
       {
         "Authorization" => "Bearer #{@api_key}",
-        "User-Agent" => "mailkube-ruby/#{VERSION}",
+        "User-Agent" => user_agent,
         "Content-Type" => "application/json",
         "Accept" => "application/json"
       }
     end
 
+    # This gem's token, plus any suffix a wrapping tool supplied.
+    #
+    # The SDK token always leads, so attribution of the SDK itself never depends on what the
+    # wrapper chose to call itself.
+    #
+    # @return [String] the User-Agent value.
+    def user_agent
+      agent = "mailkube-ruby/#{VERSION}"
+      @user_agent_suffix.empty? ? agent : "#{agent} #{@user_agent_suffix}"
+    end
+
     # Join a relative path onto the base URL, attach the query, and refuse any absolute URL off
     # the base URL's origin.
     #

data/lib/mailkube/version.rb

@@ -11,5 +11,5 @@ module Mailkube
   # semantic-release rewrites this line **in the release runner** just before the gem is built, and
   # commits nothing back to `main` (see `.rules/RELEASE.md`). So a checkout reports `0.0.0` and an
   # installed gem reports the real version: that is intended, not a bug to fix by hardcoding one.
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/mailkube/webhooks.rb

@@ -5,7 +5,7 @@ require "time"
 require "json"
 
 module Mailkube
-  # Webhook signature verification.
+  # Webhook signature verification and event parsing.
   #
   # Verification is pure and dependency-free: no client instance, no configuration, so you call
   # it directly inside your webhook handler.
@@ -89,6 +89,39 @@ module Mailkube
       parse_event(verify_signature(payload: payload, headers: headers, secret: secret, tolerance: tolerance))
     end
 
+    # Produce the `X-Webhook-Sig` value for a payload, the mirror of {verify_signature}.
+    #
+    # This exists so anything that produces a delivery — a fixture, a local replay tool, a fake
+    # endpoint in your own suite — computes the signature the way this module verifies it. A
+    # reimplementation from the docs above agrees with its author's reading of the prose rather
+    # than with this SDK, and the two drift silently. Production code verifies; it does not sign.
+    #
+    # Freshness is not this method's concern: it signs the timestamp it is given, so replaying an
+    # old capture reproduces the original signature exactly.
+    #
+    # @param id [String] the `X-Webhook-Id` value.
+    # @param timestamp [String] the `X-Webhook-Ts` value, ISO-8601.
+    # @param payload [String] the raw body that will be sent.
+    # @param secret [String] the endpoint's signing secret.
+    # @return [String] the header value, including the `sha256=` prefix.
+    def self.sign(id:, timestamp:, payload:, secret:)
+      SIGNATURE_PREFIX + signature_hex(id, timestamp, payload, secret)
+    end
+
+    # Return the hex HMAC-SHA256 over the contract's signed input.
+    #
+    # One implementation, so signing and verifying cannot disagree.
+    #
+    # @param id [String] the `X-Webhook-Id` value.
+    # @param timestamp [String] the `X-Webhook-Ts` value.
+    # @param payload [String] the raw body.
+    # @param secret [String] the signing secret.
+    # @return [String] the hex digest, without the prefix.
+    def self.signature_hex(id, timestamp, payload, secret)
+      OpenSSL::HMAC.hexdigest("SHA256", secret, "#{id}.#{timestamp}.#{payload}")
+    end
+    private_class_method :signature_hex
+
     # Normalize a header mapping to lowercase, dashed names.
     #
     # This accepts more than a Hash on purpose. `ActionDispatch::Http::Headers` is `Enumerable`
@@ -139,7 +172,7 @@ module Mailkube
     # @param secret [String] the signing secret.
     # @raise [SignatureVerificationError] when the digests differ.
     def self.check_signature(payload, id, timestamp, signature, secret)
-      expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{id}.#{timestamp}.#{payload}")
+      expected = signature_hex(id, timestamp, payload, secret)
       provided = signature.delete_prefix(SIGNATURE_PREFIX)
       # Length is compared first because `fixed_length_secure_compare` raises on a mismatch, and
       # the length of a hex digest is not a secret.

data/sig/mailkube/client.rbs

@@ -3,7 +3,8 @@ module Mailkube
     attr_reader emails: Resources::Emails
     attr_reader scheduled_emails: Resources::ScheduledEmails
 
-    def initialize: (?api_key: String?, ?base_url: String?, ?timeout: Numeric, ?http: _HttpAdapter?) -> void
+    def initialize: (?api_key: String?, ?base_url: String?, ?timeout: Numeric, ?http: _HttpAdapter?,
+                     ?user_agent_suffix: String?) -> void
     def base_url: () -> String
   end
 end

data/sig/mailkube/config.rbs

@@ -7,8 +7,9 @@ module Mailkube
     attr_reader base_url: String
     attr_reader timeout: Numeric
 
-    def initialize: (?api_key: String?, ?base_url: String?, ?timeout: Numeric) -> void
+    def initialize: (?api_key: String?, ?base_url: String?, ?timeout: Numeric, ?user_agent_suffix: String?) -> void
     def default_headers: () -> Hash[String, String]
+    def user_agent: () -> String
     def build_url: (String, ?Hash[String, String]) -> String
   end
 end

data/sig/mailkube/webhooks.rbs

@@ -12,6 +12,8 @@ module Mailkube
     def self.parse_event: (String) -> Events::Event
     def self.verify: (payload: String, headers: _HeaderMap, secret: String,
                       ?tolerance: Integer) -> Events::Event
+    def self.sign: (id: String, timestamp: String, payload: String, secret: String) -> String
+    def self.signature_hex: (String, String, String, String) -> String
     def self.check_freshness: (String, Integer) -> void
     def self.check_signature: (String, String, String, String, String) -> void
     def self.normalize_headers: (_HeaderMap) -> Hash[String, String]

data/sig/mailkube.rbs

@@ -29,7 +29,8 @@ module Mailkube
     def request_json: (RequestSpec) -> Hash[String, untyped]
   end
 
-  def self.new: (?api_key: String?, ?base_url: String?, ?timeout: Numeric, ?http: _HttpAdapter?) -> Client
+  def self.new: (?api_key: String?, ?base_url: String?, ?timeout: Numeric, ?http: _HttpAdapter?,
+                 ?user_agent_suffix: String?) -> Client
   def self.error_class_for: (Integer) -> Class
 
   STATUS_ERRORS: Hash[Integer, Class]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mailkube
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Mailtactic, Corp.