mailkite 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42cf7ba9f50876399828e00154066736c0210841c052f13c985d55fdce4f1d44
-  data.tar.gz: 56fc0377973778fd28f55386045df4df9b160813e4f601e86694d5393eef91c5
+  metadata.gz: cf95721d75808a7648a0d5c5528a5b24cebe649e4e7b4f2aa7cf96309492c4df
+  data.tar.gz: fd40da8370ad8ad24b538613a29a8b623226901a8db8e5bc6a4b0b3ebd1ec709
 SHA512:
-  metadata.gz: d9682dccd33207a1fdf67ac6ec85461c897bdf245c1f8bae43c3363c231e431434bd75c433ffa2e8f66ee5619b878e5672af3b598d32732989222173e0105391
-  data.tar.gz: cff4c8b4683f22ef86abe586238a6d44367658667f6dded3a7257900760fb202a68e6fec2fc81c8d0b483b657d93004962a2d6162fc3ed23a30f56cba2558002
+  metadata.gz: 96e4a3c87afd08886338448d1edf8bfd83d7433733bba220cb892647249c923d46dde87df440ce78c84f1301b734fec480b89d9ee2e54f8eef2e528fec4af4dc
+  data.tar.gz: d7b4ccb09e09a382e7d9bef520115c50aa06c635646763b73cea18bc133326b6080371a56037b3f05ccb5461b53b9d2369d4f5bfde84dedd1e5770d0fe0443d2

data/lib/mailkite.rb

@@ -11,10 +11,11 @@ require "net/http"
 require "uri"
 require "json"
 require "openssl"
+require "base64"
 require "cgi"
 
 module Mailkite
-  VERSION = "0.3.0"
+  VERSION = "0.4.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
@@ -54,6 +55,65 @@ module Mailkite
     diff.zero?
   end
 
+  # The canonical body to return from a webhook handler so MailKite marks the
+  # delivery acknowledged. Returns the exact string `{"status":"ok"}`.
+  def self.reply_ok
+    '{"status":"ok"}'
+  end
+
+  # Encrypt a UTF-8 string to a customer RSA public key (SPKI/PEM), producing the
+  # MailKite at-rest envelope as a compact JSON string. Hybrid scheme: a fresh
+  # AES-256-GCM content key encrypts the data, then the raw key is wrapped with
+  # RSA-OAEP (SHA-256). Local only — no network.
+  def self.encrypt(plaintext, public_key)
+    pub = OpenSSL::PKey.read(public_key)
+    fp = OpenSSL::Digest::SHA256.hexdigest(pub.to_der)
+
+    raw_key = OpenSSL::Random.random_bytes(32)
+    iv = OpenSSL::Random.random_bytes(12)
+
+    cipher = OpenSSL::Cipher.new("aes-256-gcm")
+    cipher.encrypt
+    cipher.key = raw_key
+    cipher.iv = iv
+    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")
+
+    JSON.generate({
+      "v" => 1,
+      "keyAlg" => "RSA-OAEP-256",
+      "fp" => fp,
+      "enc" => "A256GCM",
+      "iv" => Base64.strict_encode64(iv),
+      "wrappedKey" => Base64.strict_encode64(wrapped),
+      "ciphertext" => Base64.strict_encode64(ciphertext),
+    })
+  end
+
+  # Decrypt a MailKite at-rest envelope (JSON string) with the matching RSA
+  # private key (PEM), returning the original UTF-8 plaintext. Local only.
+  def self.decrypt(envelope, private_key)
+    env = envelope.is_a?(String) ? JSON.parse(envelope) : envelope
+    priv = OpenSSL::PKey.read(private_key)
+
+    iv = Base64.strict_decode64(env["iv"])
+    wrapped = Base64.strict_decode64(env["wrappedKey"])
+    ct = Base64.strict_decode64(env["ciphertext"])
+    body = ct[0...-16]
+    tag = ct[-16..]
+
+    raw_key = priv.decrypt(wrapped, rsa_padding_mode: "oaep", rsa_oaep_md: "sha256", rsa_mgf1_md: "sha256")
+
+    cipher = OpenSSL::Cipher.new("aes-256-gcm")
+    cipher.decrypt
+    cipher.key = raw_key
+    cipher.iv = iv
+    cipher.auth_tag = tag
+    (cipher.update(body) + cipher.final).force_encoding("UTF-8")
+  end
+
   class Error < StandardError
     attr_reader :status, :body
 
@@ -204,5 +264,18 @@ module Mailkite
     def verifyWebhook(signature, payload, secret, tolerance_ms = DEFAULT_TOLERANCE_MS)
       Mailkite.verify_webhook(signature, payload, secret, tolerance_ms)
     end
+
+    # Instance wrappers around the module-level crypto helpers. No network call.
+    def reply_ok
+      Mailkite.reply_ok
+    end
+
+    def encrypt(plaintext, public_key)
+      Mailkite.encrypt(plaintext, public_key)
+    end
+
+    def decrypt(envelope, private_key)
+      Mailkite.decrypt(envelope, private_key)
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mailkite
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - MailKite
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-24 00:00:00.000000000 Z
+date: 2026-06-25 00:00:00.000000000 Z
 dependencies: []
 description: Send and manage email over your own authenticated domain with MailKite.
 email: