mailcycle 0.1.0

data/lib/mailcycle/pairing.rb

@@ -0,0 +1,338 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mailcycle
+  # What a scanned pairing QR code, or a typed code, carries.
+  #
+  # `code` is the eight digits. `token` is a pairing token, from an old deep
+  # link; nothing can be looked up by it. `wrap` is the device's wrap secret,
+  # base64url; only a QR code carries it.
+  ScannedPairing = Struct.new(:code, :token, :wrap, keyword_init: true)
+
+  # One address's keys at one epoch above 0, base64url.
+  EpochKey = Struct.new(:key, :sealing_key, keyword_init: true) do
+    def inspect
+      "#<Mailcycle::EpochKey ..>"
+    end
+    alias_method :to_s, :inspect
+  end
+
+  # The address keys for one device. The server stores and relays it blindly.
+  #
+  # - `keys`: address id to its symmetric key, base64url, for mail the
+  #   account's own devices sealed.
+  # - `sealing_keys`: address id to its X25519 private key, base64url, for
+  #   mail that arrived from outside.
+  # - `epoch_keys`: a rotated address's later epochs, address id to epoch (a
+  #   string) to EpochKey. Epoch 0 stays in `keys` and `sealing_keys`, for
+  #   older readers.
+  # - `sender_name`: an agent's sender name.
+  # - `sender_names`: address id to the name set on that address, which wins
+  #   over `sender_name`.
+  #
+  # `inspect` shows counts, never the keys: they are live private key
+  # material, and would otherwise reach any log they were printed to.
+  KeyBundle = Struct.new(:keys, :sealing_keys, :epoch_keys, :sender_name, :sender_names, :issued_at,
+                         keyword_init: true) do
+    # The JSON the device reads, field for field as the app writes it.
+    def to_wire
+      out = { "keys" => keys.sort.to_h, "sealingKeys" => sealing_keys.sort.to_h }
+      unless epoch_keys.empty?
+        out["epochKeys"] = epoch_keys.sort.to_h do |id, epochs|
+          [id, epochs.sort.to_h { |epoch, key| [epoch, { "key" => key.key, "sealingKey" => key.sealing_key }] }]
+        end
+      end
+      out["senderName"] = sender_name unless sender_name.nil?
+      out["senderNames"] = sender_names.sort.to_h unless sender_names.empty?
+      out["issuedAt"] = issued_at
+      out
+    end
+
+    def to_json(*args)
+      to_wire.to_json(*args)
+    end
+
+    def self.from_wire(wire)
+      wire = Wire.object(wire)
+      strings = ->(value) { Wire.object(value).select { |_, v| v.is_a?(String) } }
+      epochs = Wire.object(wire["epochKeys"]).to_h do |id, by_epoch|
+        [id, Wire.object(by_epoch).to_h do |epoch, key|
+          key = Wire.object(key)
+          [epoch, EpochKey.new(key: Wire.text(key["key"]), sealing_key: Wire.text(key["sealingKey"]))]
+        end]
+      end
+      new(keys: strings.call(wire["keys"]), sealing_keys: strings.call(wire["sealingKeys"]), epoch_keys: epochs,
+          sender_name: Wire.maybe_text(wire["senderName"]), sender_names: strings.call(wire["senderNames"]),
+          issued_at: Wire.text(wire["issuedAt"]))
+    end
+
+    def inspect
+      "#<Mailcycle::KeyBundle keys=#{keys.length} sealing_keys=#{sealing_keys.length} " \
+        "sender_name=#{sender_name.inspect} sender_names=#{sender_names.inspect} issued_at=#{issued_at.inspect}>"
+    end
+    alias_method :to_s, :inspect
+  end
+
+  # Pairing a device, and handing it the keys for its addresses.
+  #
+  # This is the account's side of pairing, as the app does it on the "Add
+  # device" screen. The device opens what is sealed here with code this
+  # library never runs, so every byte follows the app: `pairingCore.ts`,
+  # `api/pairingApi.ts` and `handKeysTo` in `api/fleetApi.ts`.
+  #
+  # Each device has a 64-byte wrap secret. Its address keys are sealed under
+  # it, and the account keeps a copy in the device's sealed profile so it can
+  # hand over keys again when an address is assigned later. The secret reaches
+  # the account one of two ways:
+  #
+  # - Optical. The device shows the secret in its QR code
+  #   (`MC1:<code>:<wrap>`). It reaches the account without passing through
+  #   Mailcycle.
+  # - Relayed. Only the eight digits are typed, which carry no secret. The
+  #   device publishes a public key when it starts pairing, and the account
+  #   mints a secret and seals it to that key. The server relays the key, so
+  #   it could put its own in its place at pairing and read what follows. It
+  #   cannot read anything passively.
+  module Pairing
+    QR_PREFIX = "MC1:"
+    WRAP_BYTES = 64
+    WORKER_RECORD = "worker"
+
+    module_function
+
+    # Reads a scanned QR value or a typed code, as `parseScannedValue` does.
+    #
+    # Accepts `MC1:<code>`, `MC1:<code>:<wrap>`, the older JSON payload, a
+    # deep link with a token, or eight digits written any way. nil if it is
+    # none of those.
+    def parse_scanned_value(raw)
+      value = raw.to_s.strip
+      return nil if value.empty?
+
+      if value.start_with?(QR_PREFIX)
+        code, wrap = value.delete_prefix(QR_PREFIX).split(":", 2)
+        code_ok = code.to_s.match?(/\A[0-9]{8}\z/)
+        wrap_ok = wrap.nil? || wrap.match?(/\A[A-Za-z0-9_-]+\z/)
+        # The app falls through to reading the digits out of a malformed one,
+        # which picks up the 1 in `MC1`. Refused here instead.
+        return nil unless code_ok && wrap_ok
+
+        return ScannedPairing.new(code: code, token: nil, wrap: wrap)
+      end
+
+      # Older JSON payloads, from devices still showing a pre-update screen.
+      parsed = begin
+        JSON.parse(value)
+      rescue JSON::ParserError
+        nil
+      end
+      if parsed.is_a?(Hash) && parsed["type"] == "mailcycle.pairing" && parsed["token"].is_a?(String)
+        text = ->(field) { parsed[field].is_a?(String) && !parsed[field].empty? ? parsed[field] : nil }
+        return ScannedPairing.new(token: parsed["token"], code: text.call("code"), wrap: text.call("wrap"))
+      end
+
+      start = value.index("token=")
+      if start&.positive? && ["?", "&"].include?(value[start - 1])
+        token = value[(start + 6)..][/\A[A-Za-z0-9_]*/]
+        return ScannedPairing.new(code: nil, token: token, wrap: nil) unless token.empty?
+      end
+
+      digits = value.scan(/[0-9]/).first(8).join
+      digits.length == 8 ? ScannedPairing.new(code: digits, token: nil, wrap: nil) : nil
+    end
+
+    # A new wrap secret: 64 random bytes, base64url.
+    def generate_wrap_secret
+      Encoding.to_b64u(Crypto::Primitives.random_bytes(WRAP_BYTES))
+    end
+
+    # The key a device's key bundle is sealed under: the wrap secret itself.
+    #
+    # A secret of the wrong length is an error, never a fall back to a weaker
+    # key.
+    def wrapping_key(wrap_secret)
+      secret = begin
+        Encoding.from_b64u(wrap_secret)
+      rescue Base64UrlError
+        raise wrap_secret_error
+      end
+      raise wrap_secret_error unless secret.bytesize == WRAP_BYTES
+
+      secret
+    end
+
+    def wrap_secret_error
+      UnsupportedError.new("That pairing secret is not usable. Pair the device again.")
+    end
+
+    # What a relayed wrap secret is bound to.
+    def wrap_seal_aad(worker_id)
+      "mailcycle/v1/pairing-wrap:#{worker_id}"
+    end
+
+    # Seals a freshly minted wrap secret to the key the device published.
+    def seal_wrap_for_device(device_key, wrap_secret, worker_id)
+      public_key = Encoding.from_b64u(device_key)
+      Crypto::Asymmetric.seal_to_public_key(public_key, wrapping_key(wrap_secret), wrap_seal_aad(worker_id))
+    end
+
+    # Now, as JavaScript's `toISOString` writes it: `2026-09-21T10:00:00.000Z`.
+    def iso_now
+      now = Time.now.utc
+      iso_at(now.to_i, now.usec / 1000)
+    end
+
+    def iso_at(seconds, millis)
+      "#{Time.at(seconds).utc.strftime('%Y-%m-%dT%H:%M:%S')}.#{format('%03d', millis)}Z"
+    end
+  end
+
+  # Pairing, and handing a device the keys for its addresses.
+  class Devices
+    # Pairs a device with the account, as the app's "Add device" screen does.
+    #
+    # `code_or_qr` is the eight digits the device shows, or the text of its QR
+    # code. The QR code carries the device's wrap secret, so its keys reach it
+    # without passing through Mailcycle. With the digits alone the device must
+    # publish a pairing key; a secret is minted here and sealed to it, and the
+    # server relays that key, so it could put its own in its place at pairing.
+    # Prefer the QR code where there is one.
+    #
+    # `name` is sealed on this machine. An empty one takes the name the device
+    # gave. Needs the phrase and a signed-in session.
+    def pair(code_or_qr, name)
+      keys = @client.require_keys("pair a device")
+      scanned = Pairing.parse_scanned_value(code_or_qr) || ScannedPairing.new
+      if scanned.code.nil?
+        message = if scanned.token
+                    "That QR code does not carry a pairing code. Enter the 8 digits shown on the device."
+                  else
+                    "A pairing code is eight digits."
+                  end
+        raise ApiError.new(400, "invalid_code", message)
+      end
+      Pairing.wrapping_key(scanned.wrap) if scanned.wrap
+
+      preview = Wire.object(@client.http.request("POST", "/workers/pair/lookup", body: { "code" => scanned.code }))
+      session_id = Wire.text(preview["sessionId"])
+      device_key = Wire.maybe_text(preview["deviceKey"])
+      device_key = nil if device_key && device_key.empty?
+      worker_id = Vault.new_id("wkr", 10)
+
+      wrap_seal = nil
+      if scanned.wrap
+        wrap = scanned.wrap
+        transport = "optical"
+      elsif device_key
+        wrap = Pairing.generate_wrap_secret
+        wrap_seal = Pairing.seal_wrap_for_device(device_key, wrap, worker_id)
+        transport = "relayed"
+      else
+        raise UnsupportedError,
+              "This device publishes no pairing key, so its keys cannot be handed over from a typed code. " \
+              "Pass the text of its QR code instead, or pair it in the app."
+      end
+
+      given = name.to_s.strip
+      if given.empty?
+        offered = Wire.text(preview["deviceName"]).strip
+        given = offered.empty? ? "New device" : offered
+      end
+      # A device's sealed profile, as `encodeWorkerProfile` writes it.
+      profile = { "name" => given, "tags" => [], "notes" => "", "wrap" => wrap }
+      sealed = Vault.seal(keys, Pairing::WORKER_RECORD, worker_id, profile)
+
+      body = { "sessionId" => session_id, "workerId" => worker_id, "profile" => sealed, "keyTransport" => transport }
+      body["wrapSeal"] = wrap_seal.to_wire if wrap_seal
+      result = Wire.object(@client.http.request("POST", "/workers/pair", body: body))
+
+      wire = result["worker"].is_a?(Hash) ? result["worker"].dup : { "id" => worker_id }
+      wire["profile"] = sealed
+      to_device(wire)
+    end
+
+    # Hands a device the keys for every address assigned to it.
+    #
+    # Opens the device's sealed profile for its wrap secret, seals a fresh key
+    # bundle under it, and uploads that. `assign` and `unassign` call this
+    # themselves. Needs the phrase and a signed-in session.
+    def hand_over_keys(device_id)
+      keys = @client.require_keys("hand a device its keys")
+      worker = Wire.object(Wire.object(@client.http.request("GET", worker_path(device_id)))["worker"])
+
+      profile = Vault.open_or_empty(keys, Pairing::WORKER_RECORD, device_id, worker["profile"])
+      wrap = Wire.text(profile["wrap"])
+      if wrap.empty?
+        message = if worker["kind"] == "agent"
+                    "This agent was connected without its key. Remove it and connect it again."
+                  else
+                    "This device was paired without keeping its key, so it cannot open the mail. Unpair it, " \
+                      "pair it again, then assign the address."
+                  end
+        raise ApiError.new(409, "no_wrap", message)
+      end
+      wrap_key = Pairing.wrapping_key(wrap)
+
+      sender_name = Wire.text(profile["senderName"])
+      bundle = KeyBundle.new(keys: {}, sealing_keys: {}, epoch_keys: {},
+                             sender_name: sender_name.empty? ? nil : sender_name,
+                             sender_names: {}, issued_at: Pairing.iso_now)
+      inboxes = Wire.array(Wire.object(@client.http.request("GET", "/inboxes"))["inboxes"])
+      inboxes.each { |inbox| add_to_bundle(bundle, keys, device_id, Wire.object(inbox)) }
+
+      sealed = Crypto::Cipher.seal_json(wrap_key, bundle.to_wire, device_id)
+      @client.http.request("POST", "#{worker_path(device_id)}/keys", body: { "keyBundle" => sealed.to_wire })
+      nil
+    end
+
+    # Assigns an address to a device, then hands it the keys to open it.
+    #
+    # The address is assigned even if the handover fails, and the error says
+    # why. Needs the phrase and a signed-in session.
+    def assign(device_id, address_id)
+      @client.http.request("POST", "#{worker_path(device_id)}/inboxes", body: { "inboxId" => address_id })
+      hand_over_keys(device_id)
+    end
+
+    # Takes an address off a device, then hands it a bundle without that
+    # address's keys.
+    #
+    # The second step is best effort, as in the app: the address is already
+    # gone from the device either way.
+    def unassign(device_id, address_id)
+      @client.http.request("DELETE", "#{worker_path(device_id)}/inboxes/#{Mailcycle.path_segment(address_id)}")
+      begin
+        hand_over_keys(device_id)
+      rescue Error
+        nil
+      end
+      nil
+    end
+
+    private
+
+    def add_to_bundle(bundle, keys, device_id, inbox)
+      return unless inbox["assignedWorkerId"] == device_id
+
+      id = inbox["id"]
+      return unless id.is_a?(String)
+
+      # The name set on the address, opened from its sealed details.
+      meta = Vault.open_or_empty(keys, "inbox", id, inbox["meta"])
+      sender_name = Wire.text(meta["senderName"])
+      bundle.sender_names[id] = sender_name unless sender_name.empty?
+      bundle.keys[id] = Encoding.to_b64u(keys.address_symmetric_key(id))
+      bundle.sealing_keys[id] = Encoding.to_b64u(keys.address_private_key(id))
+      # Every epoch a rotated address has reached, so the device reads mail
+      # from both sides of the rotation.
+      reached = Mail.key_epoch(inbox)
+      (1..reached).each do |epoch|
+        (bundle.epoch_keys[id] ||= {})[epoch.to_s] = EpochKey.new(
+          key: Encoding.to_b64u(keys.address_symmetric_key(id, epoch: epoch)),
+          sealing_key: Encoding.to_b64u(keys.address_private_key(id, epoch: epoch))
+        )
+      end
+    end
+  end
+end

data/lib/mailcycle/trackers.rb

@@ -0,0 +1,312 @@
+# frozen_string_literal: true
+
+module Mailcycle
+  # One remote resource that was removed. `kind` is `pixel`, `image` or `link`.
+  BlockedTracker = Struct.new(:url, :host, :kind, keyword_init: true)
+
+  # What Trackers.strip_remote_content produced.
+  StripResult = Struct.new(:html, :blocked, keyword_init: true)
+
+  # Tracker stripping.
+  #
+  # Opening an email should not tell the sender that you opened it. Most HTML
+  # mail carries at least one remote resource whose only job is to report back:
+  # a 1x1 image on a per-recipient URL. Loading it leaks the open, the time,
+  # the approximate location and, across devices, how many devices you read on.
+  #
+  # Mailcycle's rule is absolute and needs no per-message decision from the
+  # reader: remote content in mail is never fetched. `Message#safe_html` is the
+  # body with everything remote removed, and `Message#blocked` is what was
+  # taken out.
+  #
+  # A remote resource hides in more than `<img src>`: `srcset`, CSS
+  # `background-image: url(...)` in a style attribute or a `<style>` block, SVG
+  # `<image href>`/`<use href>`, `<video poster>`,
+  # `<iframe>`/`<object>`/`<embed>`, and a scheme obfuscated with HTML entities
+  # (`&#104;ttps://...`) all fetch. Every one of them is covered. An `<a href>`
+  # is left alone, because it loads only when the reader clicks it.
+  #
+  # This is a port of `src/privacy/trackers.ts`, kept behaviour-for-behaviour
+  # with it so the same message reads the same way here as in the app. The
+  # JavaScript patterns run under JavaScript's rules, which are not Ruby's:
+  # `^` is the start of the text rather than of a line, `\s` includes the
+  # Unicode spaces, `\b` and `\w` are ASCII, and a case-insensitive letter
+  # never matches a non-ASCII one (Ruby's would match `ſ` for `s`). So each
+  # pattern below spells those out rather than borrowing Ruby's meaning, and
+  # the differential test runs both implementations over the same markup and
+  # requires identical output.
+  module Trackers
+    # What JavaScript's `\s` matches.
+    WS = "\t\n\v\f\r    - 

  　"
+    # JavaScript's `\w`, which is ASCII.
+    WORD = "A-Za-z0-9_"
+
+    # An ASCII word, matched without regard to case the way JavaScript's `i`
+    # flag does it.
+    def self.ci(word)
+      word.each_char.map { |c| c.match?(/[A-Za-z]/) ? "[#{c.upcase}#{c.downcase}]" : Regexp.escape(c) }.join
+    end
+
+    # Which attributes fetch a remote resource, per element. `href` is listed
+    # only for SVG `<image>`/`<use>`: an `<a href>` is a click, not an
+    # automatic load.
+    RESOURCE_ATTRS = {
+      "img" => %w[src srcset lowsrc],
+      "source" => %w[src srcset],
+      "image" => %w[xlink:href href],
+      "use" => %w[xlink:href href],
+      "video" => %w[src poster],
+      "audio" => %w[src],
+      "track" => %w[src],
+      "iframe" => %w[src],
+      "embed" => %w[src],
+      "object" => %w[data],
+      "input" => %w[src],
+      "body" => %w[background],
+      "table" => %w[background],
+      "td" => %w[background],
+      "th" => %w[background],
+      "tr" => %w[background]
+    }.freeze
+
+    # Elements that exist only to load their remote resource: drop them whole.
+    DROP_WHOLE = %w[img source].freeze
+
+    # Hosts whose presence in mail is tracking and nothing else.
+    TRACKER_HINTS = %w[
+      open. track. trk. click. email. mailstat pixel beacon sendgrid.net mailchimp list-manage hubspot
+      mktoresp omtrdc doubleclick
+    ].freeze
+
+    DIMENSION = /(?<![#{WORD}])(#{ci('width')}|#{ci('height')})[#{WS}]*=[#{WS}]*["']?[#{WS}]*([0-9]+)/
+    REMOTE = %r{\A(#{ci('http')}[sS]?:)?//}
+    # The JavaScript is `url\(\s*(['"]?)([^'")]+)\1\s*\)`, backreference and all.
+    CSS_URL = /#{ci('url')}\([#{WS}]*(['"]?)([^'")]+)\1[#{WS}]*\)/
+    STYLE_BLOCK = %r{<#{ci('style')}(?![#{WORD}])[^>]*>(.*?)</#{ci('style')}>}m
+    # The attributes group tolerates quoted values that contain `>`.
+    TAG = /<([a-zA-Z][#{WORD}:-]*)((?:"[^"]*"|'[^']*'|[^>"'])*)>/
+    HOST = %r{\A(?:#{ci('http')}[sS]?:)?//([^/?#]+)}
+    WWW = /\A#{ci('www')}\./
+    ENTITY_HEX = /&#[xX]([0-9a-fA-F]+);?/
+    ENTITY_DEC = /&#([0-9]+);?/
+    ENTITY_NAMED = /&(#{ci('amp')}|#{ci('colon')}|#{ci('sol')}|#{ci('NewLine')}|#{ci('Tab')});/
+    # `[\s\x00-\x1f]`: the control characters cover JavaScript's ASCII spaces.
+    IGNORABLE = /[\u0000-\u001f \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]+/
+    LINK = %r{#{ci('http')}[sS]?://[^#{WS}<>"')]+}
+    SPACES = /[#{WS}]+/
+    TRIM = /\A[#{WS}]+|[#{WS}]+\z/
+
+    # A leading boundary (start, whitespace or quote) keeps `href` from
+    # matching inside `xlink:href`. Groups: 1 boundary, 2 name, 3 whole value,
+    # 4/5/6 the double-quoted / single-quoted / unquoted value.
+    ATTR_PATTERNS = (RESOURCE_ATTRS.values.flatten.uniq + ["style"]).to_h do |attr|
+      [attr, /(\A|[#{WS}"'])(#{ci(attr)})[#{WS}]*=[#{WS}]*("([^"]*)"|'([^']*)'|([^#{WS}>]+))/]
+    end.freeze
+
+    module_function
+
+    def code_point(value)
+      return "" if value > 0x10ffff
+      # A lone surrogate has no UTF-8 spelling. JavaScript keeps it as it is;
+      # here it becomes the replacement character, which is not whitespace and
+      # not part of any scheme, so it decides nothing differently.
+      return "�" if value.between?(0xd800, 0xdfff)
+
+      [value].pack("U")
+    end
+
+    # Collapses HTML entities and ignorable characters.
+    #
+    # Used only to decide remoteness, so a scheme a renderer would resolve is
+    # judged by what it resolves to rather than by how it was spelled. The
+    # original text is what gets removed.
+    def canonical(value)
+      current = value
+      3.times do
+        step = current.gsub(ENTITY_HEX) { code_point(Regexp.last_match(1).to_i(16)) }
+        step = step.gsub(ENTITY_DEC) { code_point(Regexp.last_match(1).to_i) }
+        step = step.gsub(ENTITY_NAMED) do
+          case Regexp.last_match(1).downcase
+          when "amp" then "&"
+          when "colon" then ":"
+          when "sol" then "/"
+          else ""
+          end
+        end
+        break if step == current
+
+        current = step
+      end
+      current.gsub(IGNORABLE, "")
+    end
+
+    # The host of a URL, lowercased and without a leading `www.`.
+    def host_of(url)
+      match = HOST.match(canonical(utf8(url)).gsub(TRIM, ""))
+      return "" if match.nil?
+
+      match[1].sub(WWW, "").downcase
+    end
+
+    def remote?(url)
+      REMOTE.match?(canonical(url))
+    end
+
+    # The URLs inside a `srcset`: each candidate is `url [descriptor]`.
+    def srcset_urls(value)
+      value.split(",", -1).map { |candidate| candidate.gsub(TRIM, "").split(SPACES).first || "" }
+           .reject(&:empty?)
+    end
+
+    def attr_value(attrs, attr)
+      match = ATTR_PATTERNS[attr].match(attrs)
+      return nil if match.nil?
+
+      match[4] || match[5] || match[6] || ""
+    end
+
+    def remove_attr(attrs, attr)
+      attrs.sub(ATTR_PATTERNS[attr]) { Regexp.last_match(1) }
+    end
+
+    # The new value goes in as it is, never read as a replacement pattern:
+    # it is the sender's, and a `` $` `` or `$'` in it would otherwise copy the
+    # rest of the tag back in.
+    def set_attr(attrs, attr, value)
+      match = ATTR_PATTERNS[attr].match(attrs)
+      return attrs if match.nil?
+
+      "#{match.pre_match}#{match[1]}#{attr}=\"#{value.gsub('"', '&quot;')}\"#{match.post_match}"
+    end
+
+    # Pixel or ordinary blocked imagery.
+    #
+    # The distinction only affects wording; both are blocked identically.
+    def classify(tag, url)
+      smallest = tag.scan(DIMENSION).map { |_, digits| digits.to_i }.min
+      return "pixel" if smallest && smallest <= 3
+
+      host = host_of(url)
+      TRACKER_HINTS.any? { |hint| host.include?(hint) } ? "pixel" : "image"
+    end
+
+    def utf8(text)
+      value = text.to_s
+      value = value.dup.force_encoding(::Encoding::UTF_8) unless value.encoding == ::Encoding::UTF_8
+      value.valid_encoding? ? value : value.scrub
+    end
+
+    # Removes every remote resource from an HTML body.
+    #
+    # Inline `cid:` and `data:` references are left alone; they travel inside
+    # the message and fetch nothing. Everything remote goes, tracker or not,
+    # because "block only the ones that look like trackers" is a game the
+    # sender wins.
+    def strip_remote_content(html)
+      html = utf8(html)
+      blocked = []
+      seen = {}
+      record = lambda do |url, tag|
+        next if seen.key?(url)
+
+        seen[url] = true
+        blocked << BlockedTracker.new(url: url, host: host_of(url), kind: classify(tag, url))
+      end
+
+      strip_css_urls = lambda do |css|
+        css.gsub(CSS_URL) do
+          whole = Regexp.last_match(0)
+          url = Regexp.last_match(2)
+          if remote?(url)
+            record.call(url, "")
+            "url()"
+          else
+            whole
+          end
+        end
+      end
+
+      # 1) CSS url(...) inside <style> blocks.
+      #    The CSS is the text just before `</style>`, so it is replaced there
+      #    by position: searching the block for it would find a copy in the
+      #    tag's own attributes first and leave the real CSS fetching.
+      out = html.gsub(STYLE_BLOCK) do
+        block = Regexp.last_match(0)
+        css = Regexp.last_match(1)
+        finish = block.length - "</style>".length
+        block[0, finish - css.length] + strip_css_urls.call(css) + block[finish..]
+      end
+
+      # 2) Every tag: drop remote <img>/<source>, strip remote URL attributes
+      #    on other elements, and neutralize remote url() in any style
+      #    attribute.
+      out = out.gsub(TAG) do
+        tag = Regexp.last_match(0)
+        name = Regexp.last_match(1)
+        attrs = Regexp.last_match(2)
+        rewrite_tag(tag, name, attrs, record, strip_css_urls)
+      end
+
+      StripResult.new(html: out, blocked: blocked)
+    end
+
+    def rewrite_tag(tag, name, attrs, record, strip_css_urls)
+      lower = name.downcase
+      next_attrs = attrs
+
+      RESOURCE_ATTRS.fetch(lower, []).each do |attr|
+        value = attr_value(next_attrs, attr)
+        next if value.nil?
+
+        urls = attr == "srcset" ? srcset_urls(value) : [value]
+        remote = urls.find { |candidate| remote?(candidate) }
+        next if remote.nil?
+
+        record.call(remote, tag)
+        # A src-less <img> is pointless, and a permissive renderer cannot
+        # re-add a URL that is not there.
+        return "" if DROP_WHOLE.include?(lower)
+
+        next_attrs = remove_attr(next_attrs, attr)
+      end
+
+      style = attr_value(next_attrs, "style")
+      if style && !style.empty?
+        cleaned = strip_css_urls.call(style)
+        next_attrs = set_attr(next_attrs, "style", cleaned) if cleaned != style
+      end
+
+      next_attrs == attrs ? tag : "<#{name}#{next_attrs}>"
+    end
+    private_class_method :rewrite_tag
+
+    # Plain-text bodies carry trackers too, as one-pixel-equivalent link opens.
+    def find_tracking_links(text)
+      out = []
+      seen = {}
+      utf8(text).scan(LINK) do
+        url = Regexp.last_match(0)
+        host = host_of(url)
+        next if seen.key?(url)
+        next unless TRACKER_HINTS.any? { |hint| host.include?(hint) }
+
+        seen[url] = true
+        out << BlockedTracker.new(url: url, host: host, kind: "link")
+      end
+      out
+    end
+
+    # A one-line summary, as the app shows above a message.
+    def summarize_blocked(blocked)
+      return "No trackers in this message." if blocked.empty?
+
+      hosts = blocked.map(&:host).reject(&:empty?).uniq
+      noun = blocked.length == 1 ? "tracker" : "trackers"
+      case hosts.length
+      when 0 then "#{blocked.length} #{noun} blocked."
+      when 1 then "#{blocked.length} #{noun} blocked from #{hosts[0]}."
+      else "#{blocked.length} #{noun} blocked from #{hosts.length} hosts."
+      end
+    end
+  end
+end

data/lib/mailcycle/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Mailcycle
+  VERSION = "0.1.0"
+end