mailkite 0.19.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa6c0fe1916c302b913ce3ec7d39ca3b9e78633791fdfaf0d372306bc71bc134
-  data.tar.gz: 7795b6f4b60abcaadd6de5167a1326c1b0c5e5d8eb510ab4aeb141220c499459
+  metadata.gz: 95b5f3983efb7676a89dcd463f2b157071b89a3d941e581fb67625054d7d1318
+  data.tar.gz: 1f917e51b7f5a21abb4c2229b789fc66a0ea6bf5bb2f77b893915b5c25bc35c9
 SHA512:
-  metadata.gz: 836d902177a964a2094203c597a857222cef22f6f6d51eefd0ab5ddff1baecd636c5a4fb310aa1c658f84e128c2f9e99ef52b1f963f4d3d5f8d6c825f8f46b92
-  data.tar.gz: 438ec7af44244d1cffd79b609dddffcc11cbe9655dc3796a690ac7997d10fe8fc5c229a073dbbcb34cae2ec17640f367ed1659196d4fb3d0ded23e43f2a70015
+  metadata.gz: bdcc7b60ac6cc8783fd521fcbd814201ee879ce516338c6949f867b9434a00b3579fb957af6737b3b5e31561b6eb86cf51e03083b7ee54a6606be13312983f63
+  data.tar.gz: 3dca6576f92595282a98e7288464b9d8cc60ae37077781ab76548231b8b043bcd1049e6eb8db53515a56349fb7aa39131599b4e870acbecf602dfacffb765998

data/lib/mailkite.rb

@@ -15,7 +15,7 @@ require "base64"
 require "cgi"
 
 module Mailkite
-  VERSION = "0.19.0"
+  VERSION = "0.20.0"
   DEFAULT_BASE_URL = "https://api.mailkite.dev"
   # Reject webhook events older than this (ms) to block replays. Pass 0 to disable.
   DEFAULT_TOLERANCE_MS = 5 * 60 * 1000
@@ -29,7 +29,7 @@ module Mailkite
     signature.split(",").each do |seg|
       i = seg.index("=")
       next unless i
-      parts[seg[0...i].strip] = seg[(i + 1)..].strip
+      parts[seg[0...i].strip] = seg[(i + 1)..-1].strip
     end
     t = parts["t"]
     v1 = parts["v1"]
@@ -97,7 +97,7 @@ module Mailkite
     body = cipher.update(plaintext.to_s.dup.force_encoding("UTF-8")) + cipher.final
     ciphertext = body + cipher.auth_tag # GCM ct with 16-byte tag appended
 
-    wrapped = pub.encrypt(raw_key, rsa_padding_mode: "oaep", rsa_oaep_md: "sha256", rsa_mgf1_md: "sha256")
+    wrapped = rsa_oaep_encrypt(pub, raw_key)
 
     JSON.generate({
       "v" => 1,
@@ -120,9 +120,9 @@ module Mailkite
     wrapped = Base64.strict_decode64(env["wrappedKey"])
     ct = Base64.strict_decode64(env["ciphertext"])
     body = ct[0...-16]
-    tag = ct[-16..]
+    tag = ct[-16..-1]
 
-    raw_key = priv.decrypt(wrapped, rsa_padding_mode: "oaep", rsa_oaep_md: "sha256", rsa_mgf1_md: "sha256")
+    raw_key = rsa_oaep_decrypt(priv, wrapped)
 
     cipher = OpenSSL::Cipher.new("aes-256-gcm")
     cipher.decrypt
@@ -132,6 +132,96 @@ module Mailkite
     (cipher.update(body) + cipher.final).force_encoding("UTF-8")
   end
 
+  # ---- RSA-OAEP-SHA256 key wrapping ----------------------------------------
+  # `OpenSSL::PKey::PKey#encrypt`/`#decrypt` — the only API that lets us pick the OAEP
+  # digest — arrived in the openssl gem 3.0, which ships with Ruby 3.1. This gem supports
+  # Ruby 2.5+ (see the gemspec), and on anything older those methods simply do not exist:
+  # `encrypt`/`decrypt` used to die with `NoMethodError: undefined method 'encrypt'`.
+  # `public_encrypt`/`private_decrypt` are available everywhere but only offer
+  # PKCS1_OAEP_PADDING, which is OAEP with **SHA-1** — the wrong digest for our envelope.
+  #
+  # So on old openssl we do the EME-OAEP-SHA256 padding ourselves (RFC 8017 §7.1) on top of
+  # raw NO_PADDING RSA. Both paths produce and consume identical bytes; the test suite
+  # decrypts sdks/spec/encryption-vectors.json through whichever one this Ruby has, and
+  # through the fallback explicitly.
+  OAEP_NATIVE = OpenSSL::PKey::RSA.method_defined?(:encrypt) && OpenSSL::PKey::RSA.method_defined?(:decrypt)
+  private_constant :OAEP_NATIVE
+
+  OAEP_HLEN = 32 # SHA-256
+  private_constant :OAEP_HLEN
+
+  def self.rsa_oaep_encrypt(pub, data, force_fallback: false)
+    if OAEP_NATIVE && !force_fallback
+      return pub.encrypt(data, rsa_padding_mode: "oaep", rsa_oaep_md: "sha256", rsa_mgf1_md: "sha256")
+    end
+    pub.public_encrypt(oaep_encode(data, pub.n.num_bytes), OpenSSL::PKey::RSA::NO_PADDING)
+  end
+  private_class_method :rsa_oaep_encrypt
+
+  def self.rsa_oaep_decrypt(priv, data, force_fallback: false)
+    if OAEP_NATIVE && !force_fallback
+      return priv.decrypt(data, rsa_padding_mode: "oaep", rsa_oaep_md: "sha256", rsa_mgf1_md: "sha256")
+    end
+    oaep_decode(priv.private_decrypt(data, OpenSSL::PKey::RSA::NO_PADDING), priv.n.num_bytes)
+  end
+  private_class_method :rsa_oaep_decrypt
+
+  # MGF1 with SHA-256 (RFC 8017 §B.2.1).
+  def self.oaep_mgf1(seed, len)
+    out = "".b
+    counter = 0
+    while out.bytesize < len
+      out << OpenSSL::Digest::SHA256.digest(seed + [counter].pack("N"))
+      counter += 1
+    end
+    out[0, len]
+  end
+  private_class_method :oaep_mgf1
+
+  def self.oaep_xor(a, b)
+    a.unpack("C*").each_with_index.map { |x, i| x ^ b.getbyte(i) }.pack("C*")
+  end
+  private_class_method :oaep_xor
+
+  # EME-OAEP encode → the k-byte integer block RSA will raise to e.
+  def self.oaep_encode(msg, k)
+    msg = msg.b
+    ps_len = k - msg.bytesize - 2 * OAEP_HLEN - 2
+    raise OpenSSL::PKey::RSAError, "message too long for RSA-OAEP" if ps_len.negative?
+
+    db = OpenSSL::Digest::SHA256.digest("") + ("\x00".b * ps_len) + "\x01".b + msg
+    seed = OpenSSL::Random.random_bytes(OAEP_HLEN)
+    masked_db = oaep_xor(db, oaep_mgf1(seed, db.bytesize))
+    masked_seed = oaep_xor(seed, oaep_mgf1(masked_db, OAEP_HLEN))
+    "\x00".b + masked_seed + masked_db
+  end
+  private_class_method :oaep_encode
+
+  # EME-OAEP decode. Every malformed-input path falls through to ONE raise with one
+  # message: an attacker who can feed us envelopes must not learn *which* check failed
+  # (Manger's attack). This helper is for at-rest decryption, not an online oracle, but
+  # the shape costs nothing.
+  def self.oaep_decode(em, k)
+    ok = em.bytesize == k && k >= 2 * OAEP_HLEN + 2
+    raise OpenSSL::PKey::RSAError, "OAEP decoding error" unless ok
+
+    masked_seed = em[1, OAEP_HLEN]
+    masked_db = em[1 + OAEP_HLEN, k - OAEP_HLEN - 1]
+    seed = oaep_xor(masked_seed, oaep_mgf1(masked_db, OAEP_HLEN))
+    db = oaep_xor(masked_db, oaep_mgf1(seed, masked_db.bytesize))
+
+    ok &&= em.getbyte(0).zero?
+    ok &&= db[0, OAEP_HLEN] == OpenSSL::Digest::SHA256.digest("")
+
+    i = OAEP_HLEN
+    i += 1 while i < db.bytesize && db.getbyte(i).zero?
+    ok &&= i < db.bytesize && db.getbyte(i) == 1
+    raise OpenSSL::PKey::RSAError, "OAEP decoding error" unless ok
+
+    db[(i + 1)..-1] || "".b
+  end
+  private_class_method :oaep_decode
+
   class Error < StandardError
     attr_reader :status, :body
 
@@ -327,6 +417,26 @@ module Mailkite
       request("POST", "/api/domains", body)
     end
 
+    # Suggest a free, currently-unclaimed subdomain label. Read-only — it does
+    # not reserve the name. Read `base` from the response rather than
+    # hard-coding the pool zone.
+    def suggestSubdomain
+      request("GET", "/api/domains/subdomain/suggest")
+    end
+
+    # Check whether a free subdomain label can be claimed. Cheap enough to call
+    # as the user types; `reason` is safe to show verbatim.
+    def checkSubdomain(name)
+      request("GET", "/api/domains/subdomain/check?name=#{CGI.escape(name)}")
+    end
+
+    # Claim a free managed subdomain (`<label>.<base>`). Comes back already
+    # verified with an empty `dns` array — we host the zone, so there is nothing
+    # for the customer to publish.
+    def claimSubdomain(body)
+      request("POST", "/api/domains/subdomain", body)
+    end
+
     def getDomain(id)
       request("GET", "/api/domains/#{id}")
     end
@@ -428,6 +538,44 @@ module Mailkite
       request("POST", "/api/deliveries/#{id}/retry")
     end
 
+    # Replay a whole selection of webhook deliveries in one call. `body` takes deliveryIds /
+    # messageIds / threadIds (they combine), at most 50 ids. Always answers 200 with a per-id
+    # `results` array, so branch on that rather than on the status.
+    def retryDeliveries(body)
+      request("POST", "/api/deliveries/retry", body)
+    end
+
+    # Every captured attempt for one delivery, newest first — the request we sent and the
+    # response that came back. Captures are retained for 45 days.
+    def listDeliveryAttempts(id)
+      request("GET", "/api/deliveries/#{id}/attempts")
+    end
+
+    # POST stored messages to one webhook route, including mail that arrived before the route
+    # existed. `body` is { messageIds: [...] }, at most 50.
+    def deliverToRoute(id, body)
+      request("POST", "/api/routes/#{id}/deliver", body)
+    end
+
+    # Stored messages this route could be asked to deliver, newest first.
+    def listRouteCandidates(id, before = nil, limit = nil)
+      params = []
+      params << "before=#{CGI.escape(before.to_s)}" unless before.nil?
+      params << "limit=#{CGI.escape(limit.to_s)}" unless limit.nil?
+      path = "/api/routes/#{id}/candidates"
+      path += "?#{params.join('&')}" unless params.empty?
+      request("GET", path)
+    end
+
+    # --- Realtime -------------------------------------------------------
+    # Mint a short-lived, single-use token that authorises one Realtime API
+    # connection. Browsers need this because EventSource cannot set headers; the
+    # page passes it as ?token= on GET /v1/realtime. Inherits this credential's
+    # scope, expires in five minutes, and burns on first use.
+    def createRealtimeToken
+      request("POST", "/v1/realtime/token")
+    end
+
     # --- Lists ----------------------------------------------------------
     def listLists
       request("GET", "/api/lists")
@@ -509,6 +657,20 @@ module Mailkite
       request("GET", "/v1/me")
     end
 
+    # Step 1 of linking an EXISTING account: register an OAuth client for this
+    # installation (RFC 7591). No pre-shared secret — the client is public and
+    # proves itself with PKCE. Public: no API key required.
+    def registerOauthClient(body)
+      request("POST", "/oauth/register", body)
+    end
+
+    # Step 3 of linking: exchange the authorization code for an access token, or
+    # rotate a refresh token. Finish by calling getApiKey with the access token
+    # and storing the key. Public: no API key required.
+    def exchangeOauthToken(body)
+      request("POST", "/oauth/token", body)
+    end
+
     # Get the account's unrestricted API key (mk_live_…). Read-or-create: the
     # first call mints it.
     def getApiKey
@@ -555,6 +717,19 @@ module Mailkite
       request("POST", "/api/app-passwords", body)
     end
 
+    # Edit an app password's "label", "address" pattern and "protocols". The
+    # domain is fixed for the life of the password: repointing a live
+    # credential would hand its holder mail they were never granted.
+    def updateAppPassword(id, body)
+      request("PATCH", "/api/app-passwords/#{id}", body)
+    end
+
+    # Replace an app password's secret, keeping its scope. The old secret stops
+    # authenticating immediately; the new one is returned once.
+    def rotateAppPassword(id)
+      request("POST", "/api/app-passwords/#{id}/rotate")
+    end
+
     # Revoke an app password. Takes effect immediately — any IMAP session or
     # API call using it stops authenticating.
     def deleteAppPassword(id)
@@ -590,6 +765,131 @@ module Mailkite
       request("GET", "/api/billing/usage")
     end
 
+    # --- Events ---------------------------------------------------------
+    # Record one application-level fact about a user — +user.created+,
+    # +trial.expiring+, +payment.failed+. Every enabled trigger listening for
+    # that name enrolls the contact with the payload as its input. Identify the
+    # subject with "email" or "contactId", never both; pass a "dedupeKey" to
+    # make retries idempotent.
+    def sendEvent(event)
+      request("POST", "/v1/events", event)
+    end
+
+    # List recorded events, newest first — the surface for confirming a POST
+    # landed and for debugging a sequence that did not trigger.
+    def listEvents(name = nil, email = nil)
+      params = []
+      params << "name=#{CGI.escape(name.to_s)}" unless name.nil?
+      params << "email=#{CGI.escape(email.to_s)}" unless email.nil?
+      path = "/v1/events"
+      path += "?#{params.join('&')}" unless params.empty?
+      request("GET", path)
+    end
+
+    # The distinct event names this account works with — both events actually
+    # posted and ones your sequences trigger on or wait for but that may never
+    # have been sent.
+    def listEventNames
+      request("GET", "/v1/events/names")
+    end
+
+    # --- Sequences ------------------------------------------------------
+    # List your sequences, newest first, each with live enrollment counts.
+    # Archived sequences are omitted.
+    def listSequences
+      request("GET", "/v1/sequences")
+    end
+
+    # Create a sequence: a declared input shape, the steps a contact walks over
+    # time, and zero or more triggers. Created as a draft unless you pass
+    # status "active". The whole definition is validated up front.
+    def createSequence(sequence)
+      request("POST", "/v1/sequences", sequence)
+    end
+
+    # Get one sequence with its definition and live enrollment counts.
+    def getSequence(id)
+      request("GET", "/v1/sequences/#{id}")
+    end
+
+    # Edit a sequence. Changing the STEPS bumps its version and contacts already
+    # in flight keep walking the version they started on, so an edit can never
+    # make someone skip or repeat a step.
+    def updateSequence(id, sequence)
+      request("PATCH", "/v1/sequences/#{id}", sequence)
+    end
+
+    # Delete a sequence and retire every contact still walking it. The response
+    # reports how many were canceled.
+    def deleteSequence(id)
+      request("DELETE", "/v1/sequences/#{id}")
+    end
+
+    # Start a sequence for one contact directly — takes a sequence NAME or id,
+    # so "start the dunning sequence" needs no lookup. Returns the enrollment it
+    # created. Reach for sendEvent instead when your code only knows what
+    # HAPPENED and policy should decide what reacts.
+    def startSequence(sequence, body = nil)
+      request("POST", "/v1/sequences/#{sequence}/start", body)
+    end
+
+    # Stop whatever is chasing someone — pass the "cancelKey" you set when
+    # starting, or "sequence" and "email" together when you did not set one.
+    # Always answers 200 with a count, so it is safe to fire blindly.
+    def stopSequence(body)
+      request("POST", "/v1/sequences/stop", body)
+    end
+
+    # --- Triggers -------------------------------------------------------
+    # List the triggers attached to a sequence — the doors into it.
+    def listTriggers(id)
+      request("GET", "/v1/sequences/#{id}/triggers")
+    end
+
+    # Attach a trigger: when this event arrives, enroll the contact it is about.
+    # Never bumps the sequence's version and never touches anyone already in
+    # flight. The sequence needs a "from" address first.
+    def createTrigger(id, trigger)
+      request("POST", "/v1/sequences/#{id}/triggers", trigger)
+    end
+
+    # Edit a trigger, or toggle "enabled" to switch the door off without
+    # deleting it. Everyone already walking the sequence carries on.
+    def updateTrigger(id, trigger)
+      request("PATCH", "/v1/triggers/#{id}", trigger)
+    end
+
+    # Detach a trigger. Stops future enrollments through that door and nothing
+    # else.
+    def deleteTrigger(id)
+      request("DELETE", "/v1/triggers/#{id}")
+    end
+
+    # --- Enrollments ----------------------------------------------------
+    # List who is in a sequence and where each of them is. Filter with +status+.
+    def listEnrollments(id, status = nil)
+      path = "/v1/sequences/#{id}/enrollments"
+      path += "?status=#{CGI.escape(status.to_s)}" unless status.nil?
+      request("GET", path)
+    end
+
+    # Get one enrollment — which sequence, which step, and what happens next.
+    def getEnrollment(id)
+      request("GET", "/v1/enrollments/#{id}")
+    end
+
+    # Every step this enrollment has executed, with the outcome and the reason
+    # for it. This is the "why didn't step 3 fire" view.
+    def listEnrollmentRuns(id)
+      request("GET", "/v1/enrollments/#{id}/runs")
+    end
+
+    # Cancel one specific run by its enrollment id. To stop whatever is chasing
+    # a contact without knowing which run, use stopSequence.
+    def cancelEnrollment(id)
+      request("DELETE", "/v1/enrollments/#{id}")
+    end
+
     # --- Suppressions -----------------------------------------------------
     # List suppressed addresses (unsubscribes, hard bounces, spam complaints,
     # manual). Sends to a suppressed address are dropped before delivery.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mailkite
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.20.0
 platform: ruby
 authors:
 - MailKite
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-03 00:00:00.000000000 Z
+date: 2026-09-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mail
@@ -46,7 +46,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '2.6'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="