abqari 1.1.0

data/lib/abqari/helpers.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+require 'cgi'
+require 'date'
+require 'json'
+require 'time'
+require 'uri'
+
+module Abqari
+  module Helpers
+    extend self
+
+    # HTML-escape a value for safe interpolation in markup. Templates
+    # render through Erubi with `escape: true`, so `<%= value %>` already
+    # escapes via this function automatically; call `h()` explicitly only
+    # when building raw HTML strings emitted via `<%==` (e.g. `link_to`,
+    # `buy_button`, `bundle_picture_tag`), or inside a `<%==` block that
+    # interpolates an untrusted value directly.
+    def h(text)
+      CGI.escapeHTML(text.to_s)
+    end
+
+# JSON serialiser for values that will be interpolated raw into a
+# `<script>` block — JSON-LD, embedded config, etc. Plain
+# `JSON.generate` does NOT escape `<`, `>`, `&`, or the line /
+# paragraph separators U+2028/U+2029, any of which let a hostile
+# string break out of the script tag — a Folio response with
+# `"title": "x</script><script>alert(1)</script>"` ships as working
+# HTML otherwise. Folio data is bounded-trust per docs/security.md
+# §1; this helper closes the gap.
+#
+# Strategy: replace HTML- and JS-significant characters with their
+# JSON `\uXXXX` escape sequences. The output is still valid JSON
+# (round-trips through `JSON.parse`), but contains no literal `<`,
+# `>`, or `&`, so the host HTML parser sees it as inert text right
+# up to the closing `</script>` we emit ourselves.
+#
+# Always use `<%== script_safe_json(value) %>` inside a `<script>`
+# block. Outside `<script>`, prefer `h(value.to_json)`.
+SCRIPT_JSON_ESCAPE = {
+  '<'                    => '\u003c',
+  '>'                    => '\u003e',
+  '&'                    => '\u0026',
+  "
"               => '\u2028',
+  "
"               => '\u2029'
+}.freeze
+SCRIPT_JSON_RE = /[<>&

]/.freeze
+
+def script_safe_json(value)
+  JSON.generate(value).gsub(SCRIPT_JSON_RE, SCRIPT_JSON_ESCAPE)
+end
+
+    # Validate a URL for use in href / src attributes. Returns the
+    # RAW (un-escaped) URL when it's a same-origin path or an http(s)/
+    # mailto URL; returns nil otherwise. Blocks `javascript:`, `data:`
+    # (HTML), `vbscript:` and other scheme-based XSS vectors. Use
+    # whenever a URL comes from outside author-controlled content
+    # (Folio buy_url, fetched data, etc.).
+    #
+    # HTML-escaping is the CALLER's job. In a template, `<%= sanitized_url(u) %>`
+    # escapes once via Erubi's auto-escaping — correct. Do NOT escape
+    # here as well: returning pre-escaped output double-escapes any URL
+    # with a query string (`?a=1&b=2` → `&amp;amp;`) in every `<%=`
+    # context. Helpers that build raw HTML strings emitted via `<%==`
+    # (`link_to`, `buy_button`, `bundle_picture_tag`) wrap the result in
+    # `h(...)` themselves.
+    #
+    # Protocol-relative URLs (`//evil.com/x`) are rejected. Browsers
+    # treat them as `<current-scheme>://evil.com/x`, so they're a
+    # cross-origin redirect vector disguised as a same-origin path.
+    # Same-origin paths must start with a single `/` followed by a
+    # non-`/` character (or be a lone `/`).
+    def sanitized_url(url)
+      return nil if url.nil?
+
+      s = url.to_s.strip
+      return nil if s.empty?
+      return nil if s.start_with?('//')
+      return s if s.start_with?('/', '#')
+
+      begin
+        uri = URI.parse(s)
+      rescue URI::InvalidURIError
+        return nil
+      end
+
+      return nil unless uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS) || uri.is_a?(URI::MailTo)
+      return nil if uri.is_a?(URI::HTTP) && uri.host.to_s.empty?
+
+      uri.to_s
+    end
+
+    # The stricter sibling of `sanitized_url`, for URLs that arrive from
+    # a third party rather than from the site's own content — webmention
+    # authors, syndication payloads, anything a stranger can put on the
+    # wire. Returns the URL when it is an absolute `http`/`https` URL
+    # with a host, and `nil` otherwise.
+    #
+    # Two differences from `sanitized_url`, both deliberate:
+    #
+    #   * `mailto:` is rejected. A remote profile link or avatar has no
+    #     business being a mail link, and it renders as a clickable
+    #     `href` the reader can't distinguish from a web link.
+    #   * Same-origin forms (`/path`, `#frag`) are rejected. A stranger's
+    #     "profile URL" resolving into YOUR site is either a mistake or
+    #     an attempt to borrow your origin's credibility.
+    #
+    # What both reject, and the reason this exists at all: HTML-escaping
+    # does nothing to a URL scheme. `javascript:alert(1)` survives
+    # `CGI.escapeHTML` unchanged and stays executable inside an `href`,
+    # so escaping alone is not a defence for attacker-supplied URLs.
+    def external_http_url(url)
+      return nil if url.nil?
+
+      s = url.to_s.strip
+      return nil if s.empty?
+
+      begin
+        uri = URI.parse(s)
+      rescue URI::InvalidURIError
+        return nil
+      end
+
+      return nil unless uri.is_a?(URI::HTTP) # URI::HTTPS subclasses this
+      return nil if uri.host.to_s.empty?
+
+      uri.to_s
+    end
+
+    # Truncate `text` so the visible result (kept content + omission)
+    # is at most `length` characters. When `omission` is longer than
+    # `length` the budget for content is zero — falling back to a
+    # negative slice would silently return the LAST N chars of the
+    # text (Ruby's `String#[]` with a negative second arg returns nil
+    # or the trailing window). Clamp the slice width to 0 so the
+    # caller gets just the omission, not a surprise suffix.
+    def truncate(text, length: 100, omission: '…')
+      return '' if text.nil?
+
+      text = text.to_s
+      return text if text.length <= length
+
+      slice_width = [length - omission.length, 0].max
+      text[0, slice_width].rstrip + omission
+    end
+
+    def pluralize(count, singular, plural: nil)
+      word = count.to_i == 1 ? singular : (plural || "#{singular}s")
+      "#{count} #{word}"
+    end
+
+    # Count words in a string. Used for JSON-LD `wordCount` and any UI
+    # that surfaces word counts.
+    #
+    # Tags are stripped first (same as `reading_time`) because callers
+    # pass RENDERED HTML — `page.content`, not the markdown source. A
+    # naive `\S+` split over markup counts every attribute as a word,
+    # which inflated `wordCount` by roughly the tag density of the
+    # page. Commonmarker 2.x made that starkly visible: its heading
+    # anchors repeat the heading text in both `aria-label` and
+    # `data-heading-content`, so each heading silently added several
+    # phantom "words" to the structured data search engines read.
+    def word_count(text)
+      text.to_s.gsub(/<[^>]+>/, ' ').scan(/\S+/).length
+    end
+
+    # Format a date or time. Default format is "1 January 2026"
+    # (day month-name year, no comma). Callers can override with any
+    # strftime format string — e.g. `format: '%Y'` for year-only.
+    def local_time(time, format: '%-d %B %Y')
+      to_time(time).strftime(format)
+    end
+
+    # Whole years between the given year (or date) and today. Useful in
+    # about pages — "with over <%= years_since(2002) %> years of experience"
+    # — so the number doesn't go stale every January.
+    #
+    # Accepts an integer year or any value `to_time` understands.
+    def years_since(year_or_date, today: Date.today)
+      from = year_or_date.is_a?(Integer) ? Date.new(year_or_date, 1, 1) : to_time(year_or_date).to_date
+      diff = today.year - from.year
+      diff -= 1 if today.month < from.month || (today.month == from.month && today.day < from.day)
+      [diff, 0].max
+    end
+
+    def time_ago(time)
+      seconds = (Time.now - to_time(time)).to_i
+
+      case seconds
+      when 0..59             then 'just now'
+      when 60..3599          then "#{pluralize(seconds / 60,     'minute')} ago"
+      when 3600..86_399      then "#{pluralize(seconds / 3600,   'hour')} ago"
+      when 86_400..2_591_999 then "#{pluralize(seconds / 86_400, 'day')} ago"
+      else local_time(time)
+      end
+    end
+
+    # Inverse of time_ago. "in 3 hours", "in 2 weeks", "in 4 months". Used
+    # by the scheduled-post banner so the author sees how far away a future
+    # date actually is.
+    def time_until(time)
+      seconds = (to_time(time) - Time.now).to_i
+      return time_ago(time) if seconds <= 0
+
+      case seconds
+      when 0..59                 then 'in less than a minute'
+      when 60..3599              then "in #{pluralize(seconds / 60,         'minute')}"
+      when 3600..86_399          then "in #{pluralize(seconds / 3600,       'hour')}"
+      when 86_400..604_799       then "in #{pluralize(seconds / 86_400,     'day')}"
+      when 604_800..2_591_999    then "in #{pluralize(seconds / 604_800,    'week')}"
+      when 2_592_000..31_535_999 then "in #{pluralize(seconds / 2_592_000,  'month')}"
+      else                            "in #{pluralize(seconds / 31_536_000, 'year')}"
+      end
+    end
+
+    def link_to(text, url, **attrs)
+      # `sanitized_url` now returns a raw URL, so escape it here — this
+      # method returns a full <a> tag emitted via `<%==` (raw), so no
+      # auto-escaping downstream will do it for us.
+      safe_url = h(sanitized_url(url) || '#')
+      attrs_str = attrs.map { |k, v| %(#{h(k.to_s)}="#{h(v.to_s)}") }.join(' ')
+      attrs_str = " #{attrs_str}" unless attrs_str.empty?
+      %(<a href="#{safe_url}"#{attrs_str}>#{h(text)}</a>)
+    end
+
+    def excerpt(text, words: 50, omission: '…')
+      stripped = text.to_s.gsub(/<[^>]+>/, '').strip
+      arr = stripped.split(/\s+/)
+      return stripped if arr.length <= words
+
+      "#{arr[0, words].join(' ')}#{omission}"
+    end
+
+    def reading_time(text, wpm: 200)
+      stripped = text.to_s.gsub(/<[^>]+>/, '')
+      word_count = stripped.split(/\s+/).length
+      # Clamp wpm to ≥1 (a `wpm: 0` would divide to Infinity → FloatDomainError)
+      # and the result to ≥1 minute (empty text shouldn't read "0 min read").
+      minutes = [(word_count / [wpm.to_f, 1.0].max).ceil, 1].max
+      "#{minutes} min read"
+    end
+
+    # Latin letters that NFKD leaves alone, because their stroke or
+    # ligature is part of the letterform rather than a combining mark.
+    # Without these they'd hit the `[^a-z0-9]` strip and vanish — the
+    # same silent-deletion bug diacritic folding fixes ("Ø" → "", so
+    # "Åland Ø" would slug to "aland"). Keyed on the lowercase form;
+    # `downcase` runs first.
+    NON_DECOMPOSING_LETTERS = {
+      'ø' => 'o', 'đ' => 'd', 'ð' => 'd', 'ł' => 'l', 'ħ' => 'h',
+      'ı' => 'i', 'ŧ' => 't', 'æ' => 'ae', 'œ' => 'oe', 'ß' => 'ss',
+      'þ' => 'th'
+    }.freeze
+    NON_DECOMPOSING_LETTERS_RE = Regexp.union(NON_DECOMPOSING_LETTERS.keys).freeze
+
+    # Turn arbitrary text into a URL-safe slug.
+    #
+    # Diacritics are FOLDED, not dropped. NFKD decomposition splits "é"
+    # into "e" plus a combining acute, and removing the combining marks
+    # leaves the base letter behind. Without that step the `[^a-z0-9]`
+    # strip below deletes the whole character: "Café" became "caf" and
+    # "Mabrūk" became "mabr-k". That matters because this function
+    # builds public taxonomy URLs (`/tags/:slug/`) as well as internal
+    # ids — a transliterated tag would otherwise get a mangled URL.
+    #
+    # Non-Latin scripts (Arabic, CJK) have no Latin base letter to fold
+    # to and still slugify to "", which `Page::Path#render_permalink`
+    # catches with an explicit error.
+    def slugify(text)
+      s = text.to_s
+      # Path-derived strings reach here tagged ASCII-8BIT, and
+      # `unicode_normalize` refuses binary input outright. Re-tag as
+      # UTF-8 (the bytes almost always already are), then drop any
+      # sequence that isn't — `valid_encoding?` alone can't be trusted
+      # here, since every byte string is "valid" as ASCII-8BIT.
+      s = s.dup.force_encoding(Encoding::UTF_8) unless s.encoding == Encoding::UTF_8
+      s = s.scrub('') unless s.valid_encoding?
+      s = s.unicode_normalize(:nfkd).gsub(/\p{Mn}/, '')
+      s.downcase
+       .gsub(NON_DECOMPOSING_LETTERS_RE) { |c| NON_DECOMPOSING_LETTERS[c] }
+       .gsub(/[^a-z0-9]+/, '-')
+       .gsub(/\A-|-\z/, '')
+    end
+
+    # Render a markdown string to HTML. For frontmatter prose fields
+    # (publication excerpts, bundle/series descriptions) that authors
+    # write with bold, italics, links, paragraphs, lists — the same
+    # markdown they'd use in a page body. Uses the engine's standard
+    # `MARKDOWN_OPTIONS` so the dialect (tables, footnotes, autolinks,
+    # raw HTML) matches what `Page#content` produces.
+    #
+    # Returns '' for nil/empty input so the caller can `<%== markdown(...) %>`
+    # unconditionally without an extra `if` guard.
+    def markdown(text)
+      return '' if text.nil? || text.to_s.strip.empty?
+
+      Commonmarker.to_html(text.to_s, options: Page::MARKDOWN_OPTIONS)
+    end
+
+    def to_time(value)
+      case value
+      when Time then value
+      when Date then value.to_time
+      else Time.parse(value.to_s)
+      end
+    end
+  end
+end

data/lib/abqari/hooks.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Abqari
+  # Plugin hook registry. Plugins register named-event callbacks; the
+  # engine invokes them at known points during the build.
+  #
+  # Two flavours:
+  #
+  #   - `register(event, &block)` + `run(event, ...)` — event-style.
+  #     Every registered callback is called for its side effect; the
+  #     return value is ignored.
+  #
+  #   - `register(event, &block)` + `run_filter(event, value, ...)` —
+  #     filter-style. The value is threaded through every callback;
+  #     each callback returns the (possibly modified) value, and the
+  #     final result is what the engine consumes downstream.
+  #
+  # Events exposed by the engine (see docs/plugins.md for the canonical
+  # list):
+  #
+  #   Lifecycle:
+  #     :before_build         (site)            — Site#build entry
+  #     :after_load_pages     (site)            — after `load_pages`, before generators
+  #     :after_generate       (site)            — after `generate_all`
+  #     :before_render_page   (site, page)      — per page, before its render call
+  #     :after_build          (site)            — Site#build exit (success or failure)
+  #
+  #   Filters:
+  #     :post_process         (html, site, page) -> html
+  #     :resolved_frontmatter (fm, page)         -> fm
+  #
+  # Thread safety: registration and run iterate over a snapshot of the
+  # callback list, so registering inside a hook callback is safe (the
+  # new callback fires on the next event, not the current one).
+  module Hooks
+    @hooks = Hash.new { |h, k| h[k] = [] }
+    @mutex = Mutex.new
+
+    class << self
+      # Register a callback for `event`. Returns the block for chaining.
+      def register(event, &block)
+        raise ArgumentError, "Hooks.register requires a block (event: #{event.inspect})" unless block
+
+        @mutex.synchronize { @hooks[event] << block }
+        block
+      end
+
+      # Run every callback registered for `event`. Each return value is
+      # discarded; use `run_filter` if you need to transform a value.
+      def run(event, *args)
+        snapshot = @mutex.synchronize { @hooks[event].dup }
+        snapshot.each do |hook|
+          hook.call(*args)
+        rescue StandardError => e
+          Log.error "plugin hook #{event} crashed: #{e.class}: #{e.message}"
+          e.backtrace&.first(5)&.each { |line| Log.error "  #{line}" }
+          # Re-raise — a misbehaving plugin should fail the build, not
+          # silently produce wrong output. Operators can debug from
+          # the logged backtrace.
+          raise
+        end
+      end
+
+      # Thread `value` through every callback registered for `event`.
+      # Each callback receives `(value, *args)` and returns the new
+      # value. Final value flows back to the caller.
+      def run_filter(event, value, *args)
+        snapshot = @mutex.synchronize { @hooks[event].dup }
+        snapshot.each do |hook|
+          value = hook.call(value, *args)
+        rescue StandardError => e
+          Log.error "plugin filter #{event} crashed: #{e.class}: #{e.message}"
+          e.backtrace&.first(5)&.each { |line| Log.error "  #{line}" }
+          raise
+        end
+        value
+      end
+
+      # Reset the registry. Used in tests and any caller that wants a
+      # fresh hook table — the engine itself doesn't currently clear
+      # between rebuilds (plugins survive incremental rebuilds, matching
+      # Jekyll's _plugins/ semantics).
+      def clear!
+        @mutex.synchronize { @hooks = Hash.new { |h, k| h[k] = [] } }
+      end
+
+      # Read-only snapshot of the current registry — useful in tests
+      # and for `bin/audit` style introspection.
+      def registered_events
+        @mutex.synchronize { @hooks.keys.dup }
+      end
+
+      def count(event)
+        @mutex.synchronize { @hooks[event].size }
+      end
+    end
+  end
+
+  # Plugin auto-loader. Walks `<site_root>/plugins/**/*.rb` once at
+  # Site construction time and `Kernel#load`s each file in sorted
+  # order. Plugins are conventionally tiny Ruby files that call
+  # `Abqari::Hooks.register` to wire themselves into the lifecycle.
+  #
+  # Why `load` instead of `require`: `require` caches by path, so a
+  # plugin edit isn't reloaded on subsequent Site.new calls. `load`
+  # re-executes every time — important for the dev-server case where
+  # editing a plugin file should re-register its hooks on the next
+  # incremental rebuild.
+  #
+  # The hook table is NOT cleared between reloads. A plugin that
+  # registers in its top-level body will accumulate duplicate
+  # callbacks across rebuilds. Plugins that need rebuild-safe
+  # registration should use the `setup` convention (see
+  # docs/plugins.md): wrap registration in a module method called by
+  # `Abqari::Hooks.clear!`-aware sites.
+  module PluginLoader
+    PLUGIN_GLOB = File.join('plugins', '**', '*.rb')
+
+    module_function
+
+    def load_from(site_root)
+      pattern = File.join(site_root, PLUGIN_GLOB)
+      paths = Dir.glob(pattern).sort
+      return if paths.empty?
+
+      Log.info "Loading #{paths.size} plugin file(s) from #{File.join(site_root, 'plugins')}/"
+      paths.each do |path|
+        load(path)
+      rescue StandardError, ScriptError => e
+        Log.error "plugin load failed: #{path} — #{e.class}: #{e.message}"
+        e.backtrace&.first(5)&.each { |line| Log.error "  #{line}" }
+        raise
+      end
+    end
+  end
+end

data/lib/abqari/http_safe.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'socket'  # Addrinfo — the resolver the SSRF guard shares with Net::HTTP
+require 'ipaddr'
+
+module Abqari
+  # Bounded HTTP GET helper for build-time fetches.
+  #
+  # The engine pulls data from third parties (Folio publications, Google
+  # Fonts CSS + woff2 files). A misbehaving or compromised upstream that
+  # streamed a multi-gigabyte body would otherwise pin a CI runner's
+  # memory and disk. `HttpSafe.get` streams the body, caps the total
+  # bytes, and applies open/read timeouts to every call.
+  #
+  # Returns an `HttpSafe::Response` (not a Net::HTTPResponse) — callers
+  # use `.code`, `.success?`, `.body`, `.[]` for header lookup. Headers
+  # are downcased on lookup so `res['ETag']` and `res['etag']` are the
+  # same key.
+  #
+  # On size overflow: raises `HttpSafe::TooLargeError`. Callers either
+  # let it bubble (Folio falls through to its rescue → cached data) or
+  # surface it as a build failure.
+  module HttpSafe
+    class TooLargeError < StandardError; end
+
+    DEFAULT_MAX_BYTES    = 8 * 1024 * 1024 # 8 MB — generous for JSON / CSS / single woff2
+    DEFAULT_OPEN_TIMEOUT = 5
+    DEFAULT_READ_TIMEOUT = 10
+
+    Response = Struct.new(:code, :message, :headers, :body) do
+      # Case-insensitive header lookup — matches Net::HTTPResponse#[] semantics
+      # so call sites don't have to remember which casing the server returned.
+      def [](name)
+        headers[name.to_s.downcase]
+      end
+
+      def success?
+        code.to_i.between?(200, 299)
+      end
+    end
+
+    module_function
+
+    # Fetch `uri` with bounded body size and timeouts. Headers are a
+    # plain { 'Name' => 'value' } hash.
+    def get(uri,
+            headers: {},
+            max_bytes: DEFAULT_MAX_BYTES,
+            open_timeout: DEFAULT_OPEN_TIMEOUT,
+            read_timeout: DEFAULT_READ_TIMEOUT,
+            block_private: false)
+      request(:get, uri,
+              headers: headers,
+              max_bytes: max_bytes,
+              open_timeout: open_timeout,
+              read_timeout: read_timeout,
+              block_private: block_private)
+    end
+
+    # General-purpose bounded request — same streaming + cap +
+    # timeouts as `get`, parameterised by HTTP method and optional
+    # body. Used by the POSSE adapters (Mastodon/Bluesky POST) and
+    # the webmention sender (POST + HEAD) so a misbehaving upstream
+    # can't stream gigabytes into the build process's memory.
+    #
+    # Supported methods: :get, :head, :post. POSTs take a `body:`
+    # (string already-encoded — form or JSON) and a Content-Type in
+    # `headers:`.
+    def request(method, uri,
+                headers: {},
+                body: nil,
+                max_bytes: DEFAULT_MAX_BYTES,
+                open_timeout: DEFAULT_OPEN_TIMEOUT,
+                read_timeout: DEFAULT_READ_TIMEOUT,
+                block_private: false)
+      uri = URI(uri) unless uri.is_a?(URI)
+
+      # Never transmit a bearer token in cleartext. Callers that attach
+      # an Authorization header (webmention.io, POSSE adapters) must use
+      # https — an http:// endpoint would leak the token to any on-path
+      # observer / proxy log.
+      if headers.keys.any? { |k| k.to_s.casecmp?('authorization') } && uri.scheme != 'https'
+        raise ArgumentError, "refusing to send an Authorization header over #{uri.scheme}:// (cleartext) to #{uri.host}"
+      end
+
+      # SSRF guard for untrusted destinations (importer image URLs from a
+      # third-party export). Best-effort: resolve the host and refuse
+      # private / loopback / link-local addresses so a hostile export
+      # can't make the build fetch `http://169.254.169.254/…` or an
+      # internal service. (DNS-rebinding TOCTOU remains — acceptable for
+      # a local build tool.)
+      assert_public_host!(uri) if block_private
+
+      req = build_request(method, uri, body)
+      headers.each { |k, v| req[k] = v.to_s }
+
+      Net::HTTP.start(uri.host, uri.port,
+                      use_ssl: uri.scheme == 'https',
+                      open_timeout: open_timeout,
+                      read_timeout: read_timeout) do |http|
+        http.request(req) do |res|
+          response_body = method == :head ? '' : read_capped_body(res, max_bytes, uri)
+          return Response.new(res.code, res.message, flatten_headers(res), response_body)
+        end
+      end
+    end
+
+    def build_request(method, uri, body)
+      case method
+      when :get  then Net::HTTP::Get.new(uri.request_uri)
+      when :head then Net::HTTP::Head.new(uri.request_uri)
+      when :post
+        req = Net::HTTP::Post.new(uri.request_uri)
+        req.body = body if body
+        req
+      else
+        raise ArgumentError, "unsupported HTTP method: #{method.inspect}"
+      end
+    end
+
+    def read_capped_body(res, max_bytes, uri)
+      body = String.new(encoding: Encoding::ASCII_8BIT)
+      res.read_body do |chunk|
+        body << chunk
+        if body.bytesize > max_bytes
+          raise TooLargeError,
+                "response from #{uri.host} exceeded cap (#{max_bytes} bytes)"
+        end
+      end
+      body
+    end
+
+    def flatten_headers(res)
+      headers = {}
+      res.each_header { |name, value| headers[name.downcase] = value }
+      headers
+    end
+
+    class BlockedHostError < StandardError; end
+
+    # Ranges that `IPAddr#loopback?` / `#private?` / `#link_local?` do
+    # NOT already cover, but that a build must never reach.
+    #
+    # `0.0.0.0/8` is the one that matters most: `0.0.0.0` is not
+    # loopback, private or link-local by any of those predicates, yet
+    # connecting to it reaches localhost on Linux and macOS — so it was
+    # a one-token bypass of the whole guard.
+    BLOCKED_RANGES = [
+      IPAddr.new('0.0.0.0/8'),     # "this network"; 0.0.0.0 reaches localhost
+      IPAddr.new('100.64.0.0/10'), # CGNAT — carrier-internal, not public
+      IPAddr.new('192.0.0.0/24'),  # IETF protocol assignments
+      IPAddr.new('198.18.0.0/15'), # benchmarking
+      IPAddr.new('224.0.0.0/4'),   # multicast
+      IPAddr.new('240.0.0.0/4'),   # reserved, includes 255.255.255.255
+      IPAddr.new('::/128'),        # unspecified
+      IPAddr.new('ff00::/8')       # multicast
+    ].freeze
+
+    # Raise unless every address `uri.host` resolves to is public.
+    #
+    # Resolution goes through `Addrinfo.getaddrinfo` — deliberately the
+    # same resolver `Net::HTTP` will use to open the socket. The previous
+    # implementation used `Resolv.getaddresses` and fell back to parsing
+    # the host with `IPAddr`, which created a gap between what the guard
+    # checked and what the connection actually did: `Resolv` returns
+    # nothing for `http://2130706433/`, `IPAddr.new` rejects it, so the
+    # guard skipped the host — and then `getaddrinfo` expanded it to
+    # 127.0.0.1 and connected. The same held for `0x7f000001`,
+    # `017700000001`, `127.1` and `127.0.1`; every legacy `inet_aton`
+    # form was a bypass. Asking the connecting resolver removes that
+    # whole class of mismatch rather than enumerating the forms.
+    #
+    # A host that doesn't resolve here won't connect there either (same
+    # resolver), so an empty result falls through and lets the request
+    # fail with its natural "no such host" error rather than a
+    # misleading "refusing to fetch".
+    #
+    # DNS-rebinding TOCTOU remains — the address could change between
+    # this check and the connect. Acceptable for a local build tool.
+    def assert_public_host!(uri)
+      host = uri.host.to_s
+      # `URI` keeps the brackets on an IPv6 literal; the resolver
+      # wants them off.
+      probe = host.delete_prefix('[').delete_suffix(']')
+
+      addresses =
+        begin
+          Addrinfo.getaddrinfo(probe, nil, nil, :STREAM).map(&:ip_address).uniq
+        rescue StandardError
+          []
+        end
+      return if addresses.empty?
+
+      addresses.each do |addr|
+        ip = begin
+          IPAddr.new(addr)
+        rescue StandardError
+          next
+        end
+        next if public_ip?(ip)
+
+        raise BlockedHostError,
+              "refusing to fetch #{host}: resolves to non-public address #{addr}"
+      end
+    end
+
+    def public_ip?(ip)
+      # `::ffff:127.0.0.1` is loopback wearing an IPv6 hat — unwrap it
+      # so the IPv4 rules apply rather than the (much narrower) v6 ones.
+      ip = ip.native if ip.ipv4_mapped?
+
+      return false if ip.loopback? || ip.private? || ip.link_local?
+
+      BLOCKED_RANGES.none? { |range| range.include?(ip) }
+    rescue StandardError
+      # An address we can't reason about is not one we should fetch.
+      false
+    end
+  end
+end