mailkite 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42cf7ba9f50876399828e00154066736c0210841c052f13c985d55fdce4f1d44
-  data.tar.gz: 56fc0377973778fd28f55386045df4df9b160813e4f601e86694d5393eef91c5
+  metadata.gz: 16ccb6cd1fe7bcc80237e945bd42ea0f5f0f69d6fc618b955d8b0e93f70c04ef
+  data.tar.gz: 198dd419d07e5dda9fb2023ec653b600098f63f6837f11344db3e156d28c37e3
 SHA512:
-  metadata.gz: d9682dccd33207a1fdf67ac6ec85461c897bdf245c1f8bae43c3363c231e431434bd75c433ffa2e8f66ee5619b878e5672af3b598d32732989222173e0105391
-  data.tar.gz: cff4c8b4683f22ef86abe586238a6d44367658667f6dded3a7257900760fb202a68e6fec2fc81c8d0b483b657d93004962a2d6162fc3ed23a30f56cba2558002
+  metadata.gz: d61fd1fe911b68d90fb8359eb62fca139a8858d8dd3752d4930420e6ea2fdb6ed59c9264936a3582359ae407d5320946621c7ddcca151e691aeb24a6bf8977a5
+  data.tar.gz: 88ff488ba25e4ffccf1fdc4c26b5bcaf38b2a7bf7fb3d795a0f8165c08f53e6166bcb01420ec826c370895b163b83cd427ae7e984c1b97f4953eece037499d69

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.5.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,83 @@ 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
+
+  # Control-mode reply telling MailKite to mark the message as spam.
+  # Returns the exact string `{"status":"spam"}`.
+  def self.reply_spam
+    '{"status":"spam"}'
+  end
+
+  # Control-mode reply telling MailKite to drop (discard) the message.
+  # Returns the exact string `{"status":"drop"}`.
+  def self.reply_drop
+    '{"status":"drop"}'
+  end
+
+  # Control-mode reply telling MailKite to block the sender.
+  # Returns the exact string `{"status":"ok","actions":[{"type":"block-sender"}]}`.
+  def self.reply_block_sender
+    '{"status":"ok","actions":[{"type":"block-sender"}]}'
+  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
 
@@ -106,6 +184,14 @@ module Mailkite
       request("POST", "/v1/send", message)
     end
 
+    # Upload a file (base64 `content`) and get back a secure, time-limited URL to
+    # reference as a send() attachment ({ filename, url }) or link inline —
+    # instead of base64-inlining large files on every send. `file` keys:
+    # filename, content (base64), plus optional contentType and retentionDays.
+    def uploadAttachment(file)
+      request("POST", "/v1/attachments", file)
+    end
+
     # Run an inbound message through an AI agent. message keys: text (required),
     # plus optional subject/from/html/routeId/address/model.
     def agent(message)
@@ -204,5 +290,30 @@ 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 reply_spam
+      Mailkite.reply_spam
+    end
+
+    def reply_drop
+      Mailkite.reply_drop
+    end
+
+    def reply_block_sender
+      Mailkite.reply_block_sender
+    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.5.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: