shiplog 0.3.1 → 0.4.0

data/app/models/shiplog/markdown.rb

@@ -0,0 +1,233 @@
+module Shiplog
+  # A small, dependency-free Markdown subset for announcement bodies (written by an LLM, edited by an admin, shown
+  # on public pages, in the feed and in emails). XSS-safe by construction: every piece of source text is escaped
+  # before it is placed in a tag we build ourselves, and raw HTML is never passed through.
+  module Markdown
+    HEADING = /\A {0,3}(\#{1,6})[ \t]+(.*?)(?:[ \t]+\#+)?[ \t]*\z/
+    RULE = /\A {0,3}([-*_])(?:[ \t]*\1){2,}[ \t]*\z/
+    ITEM = /\A([ \t]*)([-*+]|\d+[.)])[ \t]+(.*)\z/
+    QUOTE = /\A {0,3}>[ \t]?(.*)\z/
+    LINK = /\G\[((?:\\.|[^\]\\])*)\]\(((?:[^()\\]|\\.|\([^()]*\))*)\)/
+    IMAGE = /\G!\[((?:\\.|[^\]\\])*)\]\(((?:[^()\\]|\\.|\([^()]*\))*)\)/
+    ESCAPABLE = %w[* _ [ ] ( ) ` \\ # ! -].freeze
+    LINK_URL = %r{\A(?:https?://|mailto:|#|/(?![/\\]))}i
+    IMAGE_URL = %r{\A(?:https?://|/(?![/\\]))}i
+    CONTROL_CHARS = /[[:cntrl:]]/
+
+    # Block-level HTML for +text+. Heading levels are shifted by +heading_offset+ (clamped to h1..h6). +styles+
+    # maps tag names to inline styles ({ "p" => "margin:0 0 12px;" }) for emails, where stylesheets are ignored.
+    def self.to_html(text, heading_offset: 0, styles: {})
+      html = blocks(text).map { |block| render_block_html(block, heading_offset, styles) }.join("\n")
+      html.html_safe # every fragment was escaped or built by us
+    end
+
+    # Plain text (no HTML escaping) for emails and meta descriptions; blocks are separated by a blank line.
+    def self.to_text(text)
+      blocks(text).filter_map { |block| render_block_text(block) }.join("\n\n")
+    end
+
+    # Splits the source into [:heading, level, text], [:paragraph, text], [:quote, text], [:list, ordered, items]
+    # and [:rule] blocks.
+    def self.blocks(text)
+      lines = text.to_s.gsub(/\r\n?/, "\n").split("\n")
+      result = []
+      until lines.empty?
+        line = lines.first
+        if line.strip.empty?
+          lines.shift
+        elsif (match = line.match(HEADING))
+          lines.shift
+          result << [ :heading, match[1].length, match[2] ]
+        elsif line.match?(RULE)
+          lines.shift
+          result << [ :rule ]
+        elsif line.match?(ITEM)
+          result << take_list(lines)
+        elsif line.match?(QUOTE)
+          result << [ :quote, take_while(lines) { |l| l.match(QUOTE)&.[](1) }.join("\n") ]
+        else
+          result << [ :paragraph, take_paragraph(lines).join("\n").strip ]
+        end
+      end
+      result
+    end
+    private_class_method :blocks
+
+    def self.block_start?(line)
+      line.match?(HEADING) || line.match?(RULE) || line.match?(ITEM) || line.match?(QUOTE)
+    end
+    private_class_method :block_start?
+
+    # Shifts consecutive lines for which the block returns a (non-nil) value, and returns those values.
+    def self.take_while(lines)
+      taken = []
+      while lines.any? && (value = yield(lines.first))
+        taken << value
+        lines.shift
+      end
+      taken
+    end
+    private_class_method :take_while
+
+    def self.take_paragraph(lines)
+      [ lines.shift ] + take_while(lines) { |l| l unless l.strip.empty? || block_start?(l) }
+    end
+    private_class_method :take_paragraph
+
+    # Items of one list kind. Indented items continue the list, indented non-item lines continue the last item, and
+    # blank lines are skipped only when the next non-blank line is another item of the same kind.
+    def self.take_list(lines)
+      ordered = ordered_item?(lines.first)
+      items = []
+      until lines.empty?
+        line = lines.first
+        if line.strip.empty?
+          following = lines.find { |l| !l.strip.empty? }
+          break unless following&.match?(ITEM) && !following.match?(RULE) && ordered_item?(following) == ordered
+          lines.shift
+        elsif line.match?(RULE) || (line.match?(ITEM) && ordered_item?(line) != ordered)
+          break
+        elsif (match = line.match(ITEM))
+          items << match[3].strip
+          lines.shift
+        elsif line.match?(/\A[ \t]+\S/) && !line.match?(HEADING) && !line.match?(QUOTE)
+          items[-1] = "#{items.last}\n#{line.strip}"
+          lines.shift
+        else
+          break
+        end
+      end
+      [ :list, ordered, items ]
+    end
+    private_class_method :take_list
+
+    def self.ordered_item?(line) = line.match(ITEM)[2].match?(/\d/)
+    private_class_method :ordered_item?
+
+    # In HTML mode, +styles+ (a Hash, maybe empty) stands for the html flag of the inline renderers.
+    def self.render_block_html(block, heading_offset, styles)
+      case block.first
+      when :heading
+        level = (block[1] + heading_offset).clamp(1, 6)
+        "#{open("h#{level}", styles)}#{inline(block[2], styles)}</h#{level}>"
+      when :paragraph then "#{open("p", styles)}#{inline(block[1], styles)}</p>"
+      when :quote then "#{open("blockquote", styles)}#{open("p", styles)}#{inline(block[1], styles)}</p></blockquote>"
+      when :rule then open("hr", styles)
+      when :list
+        tag = block[1] ? "ol" : "ul"
+        items = block[2].map { |item| "#{open("li", styles)}#{inline(item, styles)}</li>" }.join("\n")
+        "#{open(tag, styles)}\n#{items}\n</#{tag}>"
+      end
+    end
+    private_class_method :render_block_html
+
+    # "<p>" or, with an inline style for the tag, "<p style="...">" (the style escaped like any attribute).
+    def self.open(tag, styles) = "<#{tag}#{style(tag, styles)}>"
+    private_class_method :open
+
+    def self.style(tag, styles)
+      value = styles[tag] if styles.is_a?(Hash)
+      value.present? ? %( style="#{escape(value, true)}") : ""
+    end
+    private_class_method :style
+
+    def self.render_block_text(block)
+      case block.first
+      when :heading then inline(block[2], false)
+      when :paragraph, :quote then inline(block[1], false)
+      when :list
+        block[2].each_with_index.map { |item, i| "#{block[1] ? "#{i + 1}." : "-"} #{inline(item, false)}" }.join("\n")
+      end
+    end
+    private_class_method :render_block_text
+
+    # Scans left to right; whatever is not a recognised construct is literal (and escaped in HTML mode).
+    def self.inline(source, html)
+      out = +""
+      i = 0
+      while i < source.length
+        output, i = inline_token(source, i, html)
+        out << output
+      end
+      out
+    end
+    private_class_method :inline
+
+    # Consumes one construct (or one literal character) at index +i+; returns its output and the next index.
+    def self.inline_token(source, i, html)
+      char = source[i]
+      if char == "\\" && ESCAPABLE.include?(source[i + 1])
+        [ escape(source[i + 1], html), i + 2 ]
+      elsif char == "`" && source[i + 1] == "`"
+        run = source[i..][/\A`+/]
+        [ run, i + run.length ] # a run of backticks (such as a ``` fence) is literal text
+      elsif char == "`" && (close = source.index("`", i + 1))
+        code = source[(i + 1)...close]
+        [ html ? "#{open("code", html)}#{escape(code, true)}</code>" : code, close + 1 ]
+      elsif char == "!" && (match = source.match(IMAGE, i))
+        [ image(match[1], match[2], html), i + match[0].length ]
+      elsif char == "[" && (match = source.match(LINK, i))
+        [ link(match[1], match[2], html), i + match[0].length ]
+      elsif char == "*" && (emphasis = emphasis(source, i, html))
+        emphasis
+      else
+        [ escape(char, html), i + 1 ]
+      end
+    end
+    private_class_method :inline_token
+
+    # **strong** or *em* when a closing marker exists and the content does not start with a space.
+    def self.emphasis(source, i, html)
+      marker = source[i, 2] == "**" ? "**" : "*"
+      start = i + marker.length
+      close = closing_marker(source, start, marker)
+      return if close.nil? || close == start || source[start].match?(/\s/)
+
+      inner = inline(source[start...close], html)
+      tag = marker == "**" ? "strong" : "em"
+      [ html ? "#{open(tag, html)}#{inner}</#{tag}>" : inner, close + marker.length ]
+    end
+    private_class_method :emphasis
+
+    # Index of the next unescaped +marker+ at or after +from+.
+    def self.closing_marker(source, from, marker)
+      i = from
+      while i < source.length
+        if source[i] == "\\"
+          i += 2
+        elsif source[i, marker.length] == marker
+          return source[i + marker.length] == "*" && marker == "**" ? i + 1 : i # "***": the last two close
+        else
+          i += 1
+        end
+      end
+      nil
+    end
+    private_class_method :closing_marker
+
+    # An anchor for allowed URLs, otherwise just the (escaped) text. Plain text shows "text (url)".
+    def self.link(label, url, html)
+      text = inline(label, html)
+      return text unless allowed_url?(url, LINK_URL)
+      return (text == url ? text : "#{text} (#{url})") unless html
+
+      %(<a href="#{escape(url, true)}"#{style("a", html)}>#{text}</a>)
+    end
+    private_class_method :link
+
+    # An img tag for allowed URLs, otherwise just the escaped alt text.
+    def self.image(alt, url, html)
+      text = inline(alt, false)
+      return escape(text, html) unless html && allowed_url?(url, IMAGE_URL)
+
+      %(<img src="#{escape(url, true)}" alt="#{escape(text, true)}" loading="lazy"#{style("img", html)}>)
+    end
+    private_class_method :image
+
+    def self.allowed_url?(url, pattern) = url.match?(pattern) && !url.match?(CONTROL_CHARS)
+    private_class_method :allowed_url?
+
+    def self.escape(text, html) = html ? ERB::Util.html_escape(text).to_str : text
+    private_class_method :escape
+  end
+end

data/app/models/shiplog/newsletter/content.rb

@@ -0,0 +1,172 @@
+module Shiplog
+  module Newsletter
+    # What a newsletter says in one locale: the announcement's title, subject and body (the current translation,
+    # English when there is none), the Markdown rendered once as inline-styled HTML and as plain text, the
+    # month's feature highlights (cards with a screenshot, a sentence and a link), and the links.
+    # SendNewsletterJob builds one per locale and hands it to every message of that locale.
+    #
+    # The split rule: when there are highlights and the body has at least two "## " sections, the email shows
+    # the intro (the text before the first heading), the highlight cards in place of the body's FIRST section,
+    # then the rest of the body from the second section on ("Also improved"). Otherwise the body is shown whole.
+    # The split is made on the Markdown of the locale's text, so it works for translations whatever the headings
+    # say. Card texts come from the features' own approved (translated) entries, not from the body.
+    class Content
+      MAX_HIGHLIGHTS = 3
+      SUMMARY_LENGTH = 180
+      PREHEADER_LENGTH = 150
+      # A "## " heading at the start of a line (Markdown allows up to three leading spaces).
+      SECTION = /^ {0,3}\#{2}[ \t]/
+
+      # One highlight card: a feature's title, first sentence and permalink, and its first screenshot (absolute
+      # URL, alt text, size when the blob was analysed) or nil without one.
+      Highlight = Data.define(:title, :summary, :url, :image_url, :image_alt, :image_width, :image_height) do
+        def image? = image_url.present?
+      end
+
+      # The inline styles of the body's tags in the HTML part (email clients ignore stylesheets; see Markdown).
+      BODY_STYLES = {
+        "h1" => "margin:28px 0 10px;font-size:20px;line-height:1.3;font-weight:700;color:#1f2328;",
+        "h2" => "margin:28px 0 10px;font-size:18px;line-height:1.3;font-weight:700;color:#1f2328;",
+        "h3" => "margin:20px 0 6px;font-size:15px;line-height:1.4;font-weight:600;color:#1f2328;",
+        "h4" => "margin:16px 0 4px;font-size:15px;line-height:1.4;font-weight:600;color:#1f2328;",
+        "h5" => "margin:16px 0 4px;font-size:15px;line-height:1.4;font-weight:600;color:#1f2328;",
+        "h6" => "margin:16px 0 4px;font-size:15px;line-height:1.4;font-weight:600;color:#1f2328;",
+        "p" => "margin:0 0 12px;font-size:16px;line-height:1.6;color:#1f2328;",
+        "ul" => "margin:0 0 12px;padding:0 0 0 20px;",
+        "ol" => "margin:0 0 12px;padding:0 0 0 20px;",
+        "li" => "margin:0 0 4px;font-size:15px;line-height:1.55;color:#1f2328;",
+        "blockquote" => "margin:0 0 12px;padding:0 0 0 12px;border-left:3px solid #d1d9e0;color:#59636e;",
+        "hr" => "border:0;border-top:1px solid #d1d9e0;margin:20px 0;",
+        "code" => "font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:14px;background-color:#f6f8fa;padding:1px 4px;border-radius:3px;",
+        "img" => "display:block;max-width:100%;height:auto;border-radius:8px;margin:0 0 12px;"
+      }.freeze
+
+      attr_reader :entry, :locale
+
+      # `highlights:` replaces the ones built from the month's features (the mailer preview, with no rows).
+      def initialize(entry, locale, highlights: nil)
+        @entry = entry
+        @locale = Newsletter.locale_for(locale)
+        @highlights = highlights
+      end
+
+      def title = entry.display_title(locale).to_s
+
+      def subject = title
+
+      # The month the announcement covers ("October 2026"), in the locale when its I18n data has month names.
+      def month = Period.month_name(entry.released_on || Date.current, locale: Newsletter.i18n_locale(locale))
+
+      # The whole body as HTML, each tag inline-styled, links in the accent colour. Rendered once per Content.
+      def html = @html ||= render_html(markdown)
+
+      def text = @text ||= entry.to_text(locale)
+
+      # The body's first line, cut short, for the preheader (the preview line next to the subject).
+      def preheader = (intro_text.presence || text).lines.first.to_s.squish.truncate(PREHEADER_LENGTH)
+
+      # Up to MAX_HIGHLIGHTS of the month's approved features, in the changelog's order, each with a permalink
+      # (features without one are skipped). Built once per Content.
+      def highlights
+        @highlights ||= features.lazy.filter_map { |feature| highlight(feature) }.first(MAX_HIGHLIGHTS)
+      end
+
+      # Whether the email shows the intro, the cards and the rest instead of the whole body (the split rule).
+      def highlights_shown? = highlights.any? && sections.size >= 2
+
+      # The text before the body's first "## " heading, as HTML; nil unless the split rule applies.
+      def intro_html
+        @intro_html ||= render_html(intro_markdown) if highlights_shown?
+      end
+
+      # The body from its second "## " heading on, as HTML; nil unless the split rule applies. It opens a card, whose
+      # padding already spaces it, so the opening heading's top margin is dropped.
+      def rest_html
+        @rest_html ||= flush_top(render_html(rest_markdown)) if highlights_shown?
+      end
+
+      def intro_text
+        @intro_text ||= Markdown.to_text(intro_markdown) if highlights_shown?
+      end
+
+      def rest_text
+        @rest_text ||= Markdown.to_text(rest_markdown) if highlights_shown?
+      end
+
+      def view_url = @view_url ||= Newsletter.announcement_url(entry, locale)
+
+      def changelog_url = @changelog_url ||= Newsletter.changelog_url
+
+      def accent = Shiplog.config.newsletter_accent || "#0969da"
+
+      def logo_url = Shiplog.config.newsletter_logo_url
+
+      def address = Shiplog.config.newsletter_address
+
+      def product_name = Newsletter.product_name
+
+      # The absolute URL of an attachment's file through Active Storage's redirect route (the host's), or nil.
+      def self.image_url(attachment)
+        path = Rails.application.routes.url_helpers.rails_blob_path(attachment.blob, only_path: true)
+        Newsletter.absolute_url(path)
+      end
+
+      private
+
+      def markdown = @markdown ||= entry.to_markdown(locale).gsub(/\r\n?/, "\n")
+
+      # The body cut at its "## " headings: the text before the first one, then one String per section.
+      def sections = @sections ||= markdown.split(/(?=#{SECTION.source})/).tap { |parts| parts.shift unless parts.first.to_s.match?(SECTION) }
+
+      def intro_markdown = markdown.match?(SECTION) ? markdown.split(SECTION, 2).first.to_s : markdown
+
+      def rest_markdown = sections.drop(1).join
+
+      # The HTML with the top margin of a leading heading set to 0 (its style is BODY_STYLES', so it starts "margin:").
+      def flush_top(html)
+        html.sub(/\A(\s*<h[1-6] style=")margin:\d+px/) { "#{Regexp.last_match(1)}margin:0" }.html_safe # rubocop:disable Rails/OutputSafety
+      end
+
+      def render_html(source) = Markdown.to_html(source, styles: BODY_STYLES.merge("a" => "color:#{accent};text-decoration:underline;"))
+
+      # The month's approved features, images and this locale's translations loaded at once.
+      def features
+        period = entry.subject
+        return [] unless period.is_a?(Period)
+
+        features = period.changelog_entries.with_images_loaded.to_a.select(&:feature?)
+        Entry.preload_translations(features, locale:)
+        features
+      end
+
+      def highlight(feature)
+        url = Newsletter.absolute_url(PublicLinks.entry_url(feature))
+        return unless url
+
+        image = Shiplog.images? ? feature.ordered_images.first : nil
+        image_url = image && screenshot_url(feature, image)
+        metadata = image_url ? image.blob.metadata : {}
+        feature_title = feature.display_title(locale).to_s
+        Highlight.new(title: feature_title, summary: first_sentence(feature.display_body(locale)), url:, image_url:,
+          image_alt: (image_url ? feature.custom_image_alt(image) || feature_title : nil),
+          image_width: metadata[:width].to_i.positive? ? metadata[:width].to_i : nil,
+          image_height: metadata[:height].to_i.positive? ? metadata[:height].to_i : nil)
+      end
+
+      # A screenshot's absolute URL; nil, after a log line (no address in it), when the host's routes cannot give one.
+      def screenshot_url(feature, image)
+        self.class.image_url(image)
+      rescue StandardError => error
+        Rails.logger.warn("[shiplog] Newsletter: the screenshot of entry #{feature.id} is left out: #{error.class}")
+        nil
+      end
+
+      # The first sentence of a plain-text body (punctuation kept), cut at SUMMARY_LENGTH.
+      def first_sentence(body)
+        text = body.to_s.squish
+        match = text.match(Rewriter::SENTENCE_END)
+        (match ? text[0...match.end(0)] : text).truncate(SUMMARY_LENGTH)
+      end
+    end
+  end
+end

data/app/models/shiplog/newsletter/csv.rb

@@ -0,0 +1,32 @@
+module Shiplog
+  module Newsletter
+    # The admin's CSV export of subscribers, written by hand: the csv gem is no longer a default gem and Shiplog
+    # adds no dependency for a few lines. Every cell is quoted, and a cell that a spreadsheet would read as a
+    # formula (starting with =, +, -, @, a tab or a carriage return) gets a leading apostrophe, so an address
+    # like "=HYPERLINK(...)@evil.example" cannot run anything when the file is opened.
+    module Csv
+      HEADERS = %w[email locale status source subscribed_at confirmed_at unsubscribed_at].freeze
+      FORMULA = /\A[=+\-@\t\r]/
+
+      # The CSV text of a scope of subscribers, read in batches.
+      def self.generate(scope)
+        lines = [ line(HEADERS) ]
+        scope.find_each { |subscriber| lines << line(row(subscriber)) }
+        lines.join("\n") + "\n"
+      end
+
+      def self.row(subscriber)
+        [ subscriber.email, subscriber.locale, subscriber.status, subscriber.source,
+          *[ subscriber.created_at, subscriber.confirmed_at, subscriber.unsubscribed_at ].map { |time| time&.utc&.iso8601 } ]
+      end
+
+      def self.line(values) = values.map { |value| cell(value) }.join(",")
+
+      def self.cell(value)
+        text = value.to_s
+        text = "'#{text}" if FORMULA.match?(text)
+        %("#{text.gsub('"', '""')}")
+      end
+    end
+  end
+end

data/app/models/shiplog/newsletter/recipients.rb

@@ -0,0 +1,92 @@
+module Shiplog
+  module Newsletter
+    # The recipients of a newsletter, in batches: the host's users (config.newsletter_recipients, read in batches
+    # with find_each when the callable returns a relation) and then the confirmed subscribers. An address with an
+    # unsubscribed row (a suppression record, whatever the source of the address) is skipped, one query per
+    # batch; so is a duplicate: the first host recipient with an address wins, and a subscriber whose address a
+    # host user has is skipped. A host object without a usable email or id (or not responding to email, locale
+    # and id) is skipped with a warning that names no address, never a crash.
+    class Recipients
+      Recipient = Data.define(:key, :email, :locale, :source, :record) do
+        def host? = source == :host
+        def subscriber? = source == :subscriber
+      end
+
+      EMAIL = URI::MailTo::EMAIL_REGEXP
+
+      def initialize(batch_size: Shiplog.config.newsletter_batch_size)
+        @batch_size = batch_size
+      end
+
+      # Yields Arrays of at most batch_size Recipients (fewer once suppressed and duplicate addresses are dropped).
+      def each_batch(&block)
+        seen = Set.new
+        host_batches { |records| emit(records.filter_map { |record| host_recipient(record) }, seen, suppressed: true, &block) }
+        NewsletterSubscriber.confirmed.in_batches(of: @batch_size) do |subscribers|
+          emit(subscribers.map { |subscriber| subscriber_recipient(subscriber) }, seen, suppressed: false, &block)
+        end
+      end
+
+      # Yields each Recipient once, host users first.
+      def each(&block) = each_batch { |batch| batch.each(&block) }
+
+      # { "en" => 120, "es" => 30 }: how many recipients get each locale's email, after deduplication.
+      def counts_by_locale
+        counts = Hash.new(0)
+        each { |recipient| counts[recipient.locale] += 1 }
+        counts.sort_by { |locale, _| locale }.to_h
+      end
+
+      private
+
+      # Yields the candidates that are neither suppressed (checked in one query when `suppressed`; the confirmed
+      # subscribers' scope rules it out already) nor seen before.
+      def emit(candidates, seen, suppressed:)
+        skipped = suppressed ? suppressed_emails(candidates.map(&:email)) : Set.new
+        batch = candidates.select { |recipient| !skipped.include?(recipient.email) && seen.add?(recipient.email) }
+        yield batch if batch.any?
+      end
+
+      # The addresses among `emails` that unsubscribed (NewsletterSubscriber.suppress), lowercased.
+      def suppressed_emails(emails)
+        return Set.new if emails.empty?
+
+        NewsletterSubscriber.unsubscribed.where("lower(email) IN (?)", emails).pluck(:email).map(&:downcase).to_set
+      end
+
+      # The host's recipient objects, batch_size at a time (a relation is read with find_each).
+      def host_batches(&block)
+        callable = Shiplog.config.newsletter_recipients
+        return unless callable
+
+        records = callable.call
+        return if records.nil?
+
+        if records.respond_to?(:find_each)
+          records.find_each(batch_size: @batch_size).each_slice(@batch_size, &block)
+        else
+          records.each_slice(@batch_size, &block)
+        end
+      end
+
+      def host_recipient(record)
+        return skip("#{record.class.name}, which does not respond to email, locale and id") unless %i[email locale id].all? { |name| record.respond_to?(name) }
+        return skip("a #{record.class.name} without an id") if record.id.blank?
+
+        email = record.email.to_s.strip.downcase
+        return if email.empty? || !EMAIL.match?(email) || email.length > NewsletterSubscriber::EMAIL_MAX_LENGTH
+
+        Recipient.new(key: "#{record.class.name}/#{record.id}", email:, locale: Newsletter.locale_for(record.locale), source: :host, record:)
+      end
+
+      def subscriber_recipient(subscriber)
+        Recipient.new(key: subscriber.recipient_key, email: subscriber.email, locale: Newsletter.locale_for(subscriber.locale), source: :subscriber, record: subscriber)
+      end
+
+      def skip(what)
+        Rails.logger.warn("[shiplog] newsletter_recipients gave #{what}: skipped")
+        nil
+      end
+    end
+  end
+end

data/app/models/shiplog/newsletter/tokens.rb

@@ -0,0 +1,77 @@
+module Shiplog
+  module Newsletter
+    # The tokens in newsletter links: encrypted and signed (AES-256-GCM through ActiveSupport::MessageEncryptor,
+    # URL-safe, JSON), keyed from the host's secret_key_base, each with its own purpose so one cannot stand in for
+    # another. Nothing in a token is readable without the key (no id, no address in clear in logs or caches); a
+    # tampered or expired token decrypts to nil.
+    #   confirmation(subscriber)  the double opt-in link: the row's single-use confirmation_nonce, valid
+    #                             CONFIRMATION_VALIDITY; the nonce is cleared when the link is used or the address
+    #                             unsubscribes, so an old link confirms nothing
+    #   unsubscribe(email)        the one-click and footer unsubscribe link: the address, encrypted, so the host's
+    #                             users need no row in Shiplog; it does not expire (footers live long)
+    # The preferences page uses the subscriber's stored token instead (NewsletterSubscriber#token), rotated after
+    # each change made there.
+    #
+    # Rotating secret_key_base: call `Shiplog::Newsletter::Tokens.rotate(old_secret_key_base)` in an initializer
+    # while old unsubscribe links must keep working (they are decrypted with the old key too).
+    module Tokens
+      CONFIRMATION_VALIDITY = 7.days
+      SALT = "shiplog newsletter".freeze
+      KEY_LENGTH = 32
+
+      # The confirmation link's token, or nil when the row has no pending confirmation.
+      def self.confirmation(subscriber)
+        nonce = subscriber.confirmation_nonce
+        encryptor.encrypt_and_sign({ "nonce" => nonce }, purpose: :confirm, expires_in: CONFIRMATION_VALIDITY) if nonce.present?
+      end
+
+      # The subscriber whose pending confirmation this token is, or nil (tampered, expired, used, or unsubscribed since).
+      def self.subscriber_for(token)
+        data = read(token, :confirm)
+        nonce = data["nonce"] if data.is_a?(Hash)
+        NewsletterSubscriber.find_by(confirmation_nonce: nonce) if nonce.is_a?(String) && nonce.present?
+      end
+
+      def self.unsubscribe(email) = encryptor.encrypt_and_sign({ "email" => email.to_s.strip.downcase }, purpose: :unsubscribe)
+
+      # The address of an unsubscribe token, or nil when it does not verify.
+      def self.email_for(token)
+        data = read(token, :unsubscribe)
+        data["email"].presence if data.is_a?(Hash) && data["email"].is_a?(String)
+      end
+
+      # Adds a previous secret_key_base whose tokens must still be accepted.
+      def self.rotate(secret_key_base)
+        previous_secrets << secret_key_base.to_s
+        @encryptor = nil
+      end
+
+      def self.reset_rotation!
+        previous_secrets.clear
+        @encryptor = nil
+      end
+
+      def self.previous_secrets = (@previous_secrets ||= [])
+
+      def self.encryptor
+        @encryptor ||= ActiveSupport::MessageEncryptor.new(Rails.application.key_generator.generate_key(SALT, KEY_LENGTH), url_safe: true, serializer: JSON).tap do |encryptor|
+          previous_secrets.each { |secret| encryptor.rotate(key_generator(secret).generate_key(SALT, KEY_LENGTH)) }
+        end
+      end
+
+      def self.key_generator(secret)
+        ActiveSupport::KeyGenerator.new(secret, iterations: 1000, hash_digest_class: ActiveSupport::KeyGenerator.hash_digest_class)
+      end
+      private_class_method :key_generator
+
+      def self.read(token, purpose)
+        return if token.blank?
+
+        encryptor.decrypt_and_verify(token.to_s, purpose:)
+      rescue ActiveSupport::MessageEncryptor::InvalidMessage, ActiveSupport::MessageVerifier::InvalidSignature, ArgumentError
+        nil
+      end
+      private_class_method :read
+    end
+  end
+end