vangrail 0.1.0

data/lib/vangrail/providers.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative 'provider'
+require_relative 'providers/llmlite'
+require_relative 'providers/gateway'
+
+module Vangrail
+  # The provider registry, in the order `Provider.resolve` tries it.
+  #
+  # Order is the whole policy: local before shared. A proxy on the loopback
+  # costs nothing per call, keeps rail traffic on the machine, and needs no
+  # shared credential, so an application with one running should use it without
+  # being told to.
+  #
+  # Only vendor-neutral entries are built in. A hostname compiled into this gem
+  # is an endpoint every installation inherits whether it can reach it or not,
+  # and a credential path compiled in is worse, because it publishes where
+  # somebody's secrets live. A shared gateway is therefore registered by the
+  # application that has one, or described by environment:
+  #
+  #   Vangrail::Providers.register_gateway(name: 'hub', base_url: '...', ...)
+  #   GUARDRAILS_GATEWAY_API_BASE=...  GUARDRAILS_GATEWAY_API_KEY=...
+  #
+  # An endpoint needed for a single run needs no registration at all:
+  # GUARDRAILS_API_BASE with GUARDRAILS_API_KEY beats the whole registry.
+  module Providers
+    module_function
+
+    def install!(env = ENV)
+      Provider.registry.clear
+      Provider.register(Llmlite.provider(env))
+      register_environment_gateway(env)
+      registered_specs.each { |spec| Provider.register(Gateway.provider(spec, env)) }
+      Provider.registry
+    end
+
+    # Gateways an application asked for, in the order it asked.
+    def registered_specs
+      @registered_specs ||= []
+    end
+
+    # Registers a shared gateway and returns its Provider. Registering a name
+    # twice replaces it, so reloading an application is not a duplicate.
+    def register_gateway(name:, base_url:, models: {}, guard_preset: nil, key_env: nil,
+                         file_env: nil, pass_env: nil, key_file: nil, pass_entry: nil, env: ENV)
+      spec = Gateway::Spec.new(
+        name: name.to_s, base_url: base_url, models: models, guard_preset: guard_preset,
+        key_env: key_env, file_env: file_env, pass_env: pass_env,
+        key_file: key_file, pass_entry: pass_entry
+      )
+      registered_specs.reject! { |s| s.name == spec.name }
+      registered_specs << spec
+      Provider.register(Gateway.provider(spec, env))
+    end
+
+    def register_environment_gateway(env = ENV)
+      spec = Gateway.from_environment(env)
+      return nil unless spec
+
+      Provider.register(Gateway.provider(spec, env))
+    end
+
+    # Forgets registered gateways along with any cached credential, so a test
+    # that points a lookup at nothing gets what it asked for.
+    def reset!
+      @registered_specs = []
+      install!
+    end
+  end
+end
+
+Vangrail::Providers.install!

data/lib/vangrail/rail.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative 'result'
+
+module Vangrail
+  # The whole rail protocol: a name, the sides it applies to, and `call`.
+  #
+  #   class ShoutRail < Vangrail::Rail
+  #     def call(text, _context)
+  #       return pass if text == text.downcase
+  #
+  #       modify(text.downcase, reason: 'lowered')
+  #     end
+  #   end
+  #
+  # Deliberately not a DSL. A rail is an object with one method, so a Ruby
+  # application can write one in five lines, test it without a network, and put
+  # it in the same ordered list as the model-backed ones.
+  class Rail
+    # Three sides, not two. `:context` is text the application retrieved and is
+    # about to put in a prompt: a wiki page, a search result, a file. It is the
+    # side an attacker usually reaches without touching the application at all,
+    # and a stack that checks only what the user typed and what the model
+    # answered never looks at it.
+    SIDES = %i[input context output].freeze
+
+    # What a rail gets by default. Context is opt-in per rail, because a rail
+    # written to judge a question is rarely the right one to judge a document.
+    DEFAULT_SIDES = %i[input output].freeze
+
+    attr_reader :name, :sides
+
+    def initialize(name: nil, sides: DEFAULT_SIDES)
+      @name = (name || default_name).to_s
+      @sides = Array(sides).map(&:to_sym)
+      unknown = @sides - SIDES
+      raise ArgumentError, "unknown side(s): #{unknown.join(', ')}" unless unknown.empty?
+    end
+
+    def applies_to?(side)
+      sides.include?(side.to_sym)
+    end
+
+    # Returns a Result. `context` is a hash the engine threads through:
+    # :side, :user_input, :passages, :history, plus anything a caller adds.
+    def call(_text, _context)
+      raise NotImplementedError, "#{self.class} must implement #call"
+    end
+
+    # Does this rail need the network. Used to report a posture and to let a
+    # caller build a model-free engine on purpose.
+    def offline?
+      false
+    end
+
+    # A rail that stands in for one that could not be built, rather than a rail
+    # that ran. The engine prefers the reason from something that actually ran
+    # when both are uncertain, because "the endpoint refused the connection" is
+    # more actionable than "no endpoint was resolved".
+    def placeholder?
+      false
+    end
+
+    def to_s
+      name
+    end
+
+    private
+
+    def pass(**kwargs)
+      Result.passed(rail: name, **kwargs)
+    end
+
+    def modify(content, **kwargs)
+      Result.modified(rail: name, content: content, **kwargs)
+    end
+
+    def block(**kwargs)
+      Result.blocked(rail: name, **kwargs)
+    end
+
+    # A rail that could not reach a decision allows the text and says so. It
+    # must never look like a clean check.
+    def unchecked(reason)
+      Result.unchecked(rail: name, reason: reason)
+    end
+
+    def default_name
+      self.class.name.to_s.split('::').last
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+    end
+  end
+end

data/lib/vangrail/rails/budget.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative '../rail'
+
+module Vangrail
+  module Rails
+    # Refuses text too large to be a question.
+    #
+    # The cost of answering is paid by whoever runs the endpoint, and a public
+    # desk gives anybody a way to spend it. A megabyte pasted into the box is
+    # not a question: it is a bill, and on a metered endpoint it is somebody
+    # else's bill. The same size also dilutes whatever the instructions said,
+    # which is the mechanism the many-shot work measured, so the limit is worth
+    # having twice over.
+    #
+    # Characters rather than tokens, because counting tokens means shipping a
+    # tokeniser, and a tokeniser is a dependency and a model-specific one. The
+    # ratio is close enough for a limit: roughly four characters a token for
+    # English prose, less for code.
+    #
+    #   Rails::Budget.new(max_characters: 8_000)
+    #
+    # A separate, larger limit applies to retrieved documents, which are
+    # legitimately longer than anything a reader types and are usually clipped
+    # by the retrieval step already. Setting it to nil turns that side off.
+    #
+    # Blocks rather than truncating. A truncated question is a different
+    # question, and answering a different question well is worse than saying
+    # the box has a limit.
+    class Budget < Rail
+      DEFAULT_INPUT = 8_000
+      DEFAULT_CONTEXT = 60_000
+
+      attr_reader :max_characters, :max_context
+
+      def initialize(max_characters: DEFAULT_INPUT, max_context: DEFAULT_CONTEXT,
+                     name: 'budget', sides: %i[input context])
+        super(name: name, sides: sides)
+        @max_characters = max_characters
+        @max_context = max_context
+      end
+
+      def offline?
+        true
+      end
+
+      def cache_key(text, context)
+        "#{context[:side]}:#{text.to_s.length}"
+      end
+
+      def call(text, context)
+        limit = context[:side] == :context ? max_context : max_characters
+        return pass if limit.nil?
+
+        size = text.to_s.length
+        return pass if size <= limit
+
+        block(categories: ['over_budget'],
+              reason: "#{size} characters, over the #{limit} allowed for #{context[:side]}")
+      end
+    end
+  end
+end

data/lib/vangrail/rails/canary.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative '../rail'
+
+module Vangrail
+  module Rails
+    # A marker in the prompt that must never appear anywhere else.
+    #
+    # Every other rail that cares about the system prompt is guessing: it reads
+    # the question for a shape that looks like an extraction attempt, or reads
+    # the answer for something that looks like an instruction. This one does
+    # not have to guess. The application puts a random string in the prompt, and
+    # if that string ever comes back out, the prompt came out with it.
+    #
+    #   canary = Vangrail::Rails::Canary.generate
+    #   prompt = "#{canary}\n#{system_prompt}"
+    #   engine = Vangrail::Engine.new(output: [Vangrail::Rails::Canary.new(tokens: canary)])
+    #
+    # It is exact rather than clever, and that is the whole value: no false
+    # positives are possible on a random 16-character token, so it can block
+    # outright where a heuristic could only warn.
+    #
+    # It runs on the input side too. A question containing the canary means the
+    # reader already has the prompt from somewhere, which is worth knowing even
+    # though it is too late to prevent.
+    #
+    # What it cannot see is a paraphrase. A model asked to summarise its
+    # instructions rather than repeat them leaks the content and not the token,
+    # and this rail passes. It is one exact check, not a disclosure defence, and
+    # the policy rails still have to do their job.
+    class Canary < Rail
+      LENGTH = 16
+
+      def self.generate(length: LENGTH)
+        "canary-#{SecureRandom.alphanumeric(length)}"
+      end
+
+      attr_reader :tokens
+
+      def initialize(tokens:, name: 'canary', sides: %i[input output])
+        super(name: name, sides: sides)
+        @tokens = Array(tokens).map(&:to_s).reject(&:empty?)
+        raise ArgumentError, 'a canary rail needs at least one token' if @tokens.empty?
+      end
+
+      def offline?
+        true
+      end
+
+      def cache_key(text, _context)
+        text
+      end
+
+      def call(text, context)
+        body = text.to_s
+        # Formatting is not concealment, but a model that writes the token with
+        # a line break or a backtick in it has still leaked it, so the
+        # comparison ignores anything that is not part of the token itself.
+        flat = body.gsub(/[^A-Za-z0-9-]/, '')
+        found = tokens.select { |t| body.include?(t) || flat.include?(t.gsub(/[^A-Za-z0-9-]/, '')) }
+        return pass if found.empty?
+
+        block(categories: ['canary'], reason: reason_for(context[:side]))
+      end
+
+      private
+
+      def reason_for(side)
+        return 'the question contains a prompt canary, so the prompt has already leaked' if side == :input
+
+        'the answer contains the prompt canary'
+      end
+    end
+  end
+end

data/lib/vangrail/rails/colang_flow.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative '../colang/interpreter'
+require_relative '../rail'
+
+module Vangrail
+  module Rails
+    # A Colang flow as a rail.
+    #
+    # This is what lets a configuration folder written for the Python toolkit
+    # run here: `rails.input.flows: [self check input]` becomes one of these,
+    # the flow executes in Ruby, and its `bot refuse to respond` / `stop`
+    # becomes a blocked Result carrying the refusal text.
+    #
+    # Not memoizable by default. A flow can call any registered action, and this
+    # class cannot know whether one of them reads the passages or the history.
+    class ColangFlow < Rail
+      attr_reader :flow_name, :interpreter
+
+      def initialize(flow_name:, program:, actions:, name: nil, sides: Rail::SIDES)
+        super(name: name || flow_name, sides: sides)
+        @flow_name = flow_name
+        @interpreter = Colang::Interpreter.new(program: program, actions: actions)
+      end
+
+      def cache_key(_text, _context)
+        nil
+      end
+
+      def call(text, context)
+        outcome = interpreter.run(flow_name, context.merge(text: text))
+        case outcome.status
+        when :blocked then block(content: outcome.content, reason: outcome.reason || flow_name)
+        when :modified then modify(outcome.content, reason: outcome.reason || flow_name)
+        else pass
+        end
+      end
+    end
+  end
+end

data/lib/vangrail/rails/escalation.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require_relative '../rail'
+
+module Vangrail
+  module Rails
+    # Watches what happens after a refusal.
+    #
+    # The multi-turn attacks work because the guardrail forgets. A request is
+    # refused, the next message is the same request with the objectionable word
+    # removed, and the rail reads it as a fresh question because that is all it
+    # has ever been given. Repeat until something gets through. The published
+    # multi-turn methods differ in how they choose the rewrite, and they share
+    # that one assumption: that turn N+1 is judged without turn N.
+    #
+    # So this rail judges the sequence rather than the message. It reads
+    # `:history` from the context, which a Conversation fills in, and it has
+    # exactly two things to say:
+    #
+    #   retry_after_refusal   the last question was refused, and this one is
+    #                         that question again: mostly the same words, or a
+    #                         bare reference back to it, or a reframing opener
+    #                         ("hypothetically", "just for research") on top of
+    #                         it
+    #   repeated_refusals     several refusals in a short window, whatever this
+    #                         particular message says
+    #
+    # Both are cheap and neither is clever. A caller that never passes
+    # `:history` gets a pass with an honest `certain?` of false, because a rail
+    # that reads history and was handed none has not checked anything. A caller
+    # that passes an empty one gets a certain pass: an empty dialogue is an
+    # answer rather than a missing one.
+    #
+    # The limit is worth stating: a genuine crescendo never triggers a refusal
+    # at all until the last turn, and this rail sees nothing until one happens.
+    # It raises the cost of the cheap version of the attack, where the attacker
+    # probes until something lands. Judging a dialogue that has never been
+    # refused needs a model reading the trajectory, which is a different rail
+    # and a round trip.
+    class Escalation < Rail
+      # A retry does not have to be a paraphrase. It can be a pointer.
+      REFERENCE_BACK = /
+        \A[^.?!]{0,60}\b(?:as\s+i\s+(?:said|asked|mentioned)|like\s+i\s+(?:said|asked)|
+           (?:the|my)\s+(?:previous|last|earlier)\s+(?:question|request|message)|
+           try\s+again|answer\s+(?:it|that|the\s+question)\s+anyway|
+           just\s+(?:answer|tell|say)|come\s+on|continue|go\s+on|please\s+continue)\b
+      /xi
+
+      # The openers that exist to relabel a refused request as something else.
+      REFRAMING = /
+        \b(?:hypothetically|in\s+theory|for\s+(?:a\s+)?(?:friend|research|a\s+paper|
+           educational\s+purposes|academic\s+purposes)|purely\s+(?:academic|hypothetical)|
+           what\s+if\s+i\s+(?:told\s+you|said)|imagine\s+(?:that\s+)?you|
+           let\s+me\s+rephrase|to\s+(?:re)?phrase\s+(?:it|that)\s+differently|
+           you\s+misunderstood|that\s+is\s+not\s+what\s+i\s+(?:meant|asked))\b
+      /xi
+
+      STOP = %w[
+        the a an and or but is are was were be been being to of in on at for with
+        from by as it its this that these those i you he she they we me my your do
+        does did how what why when where can could would should will shall may
+        might must not no yes if then than so about into over under please
+      ].freeze
+
+      attr_reader :overlap, :window, :tolerance
+
+      # `overlap` is the share of this question's content words that also
+      # appeared in the refused one. Three fifths is where the corpus put it: a
+      # rewrite keeps the nouns and changes the verb, so it lands near two
+      # thirds, while a genuine follow-up on the same subject shares one or two
+      # words out of seven. Higher and the measured rewrites walk through;
+      # lower and one refusal makes the topic unaskable, which ends the
+      # conversation rather than the attack.
+      def initialize(overlap: 0.6, window: 6, tolerance: 2, name: 'escalation', sides: [:input])
+        super(name: name, sides: sides)
+        @overlap = overlap
+        @window = window
+        @tolerance = tolerance
+      end
+
+      def offline?
+        true
+      end
+
+      # Not memoizable: the same question means different things depending on
+      # what came before it, which is the entire premise of the rail.
+      def cache_key(_text, _context)
+        nil
+      end
+
+      def call(text, context)
+        # A caller that never passes :history is not threading a dialogue, and
+        # this rail has not checked anything: say so. A caller that passes an
+        # empty one is threading a dialogue that has just started, which is a
+        # real answer rather than a missing one. The distinction matters
+        # because an uncertain pass here would otherwise be the first uncertain
+        # result in every single-turn engine, and would mask the reason a
+        # model rail actually failed.
+        return unchecked('no history was provided, so nothing was compared') unless context.key?(:history)
+
+        history = Array(context[:history])
+        return pass if history.empty?
+
+        refused = history.select { |t| user?(t) && t[:blocked] }
+        return pass if refused.empty?
+
+        recent = history.last(window).count { |t| user?(t) && t[:blocked] }
+        if recent > tolerance
+          return block(categories: ['repeated_refusals'],
+                       reason: "#{recent} refused questions in the last #{window} turns")
+        end
+
+        retry_of(text.to_s, refused.last)
+      end
+
+      private
+
+      def retry_of(text, last_refusal)
+        return pass if last_refusal.nil?
+
+        shape = retry_shape(text, last_refusal[:text].to_s)
+        return pass if shape.nil?
+
+        block(categories: ['retry_after_refusal', shape].compact,
+              reason: "the previous question was refused and this one is #{describe(shape)}")
+      end
+
+      # Ordered by how much it says. A paraphrase is the strongest signal
+      # because it needs no interpretation: the same content words in a new
+      # sentence, one turn after a refusal.
+      def retry_shape(text, previous)
+        return 'paraphrase' if similar?(text, previous)
+        return 'reframed' if text.match?(REFRAMING) && shares_topic?(text, previous)
+        return 'reference_back' if text.match?(REFERENCE_BACK)
+
+        nil
+      end
+
+      def describe(shape)
+        case shape
+        when 'paraphrase' then 'the same question again'
+        when 'reframed' then 'the same question with a reframing opener'
+        else 'a request to answer it anyway'
+        end
+      end
+
+      def similar?(text, previous)
+        now = content_words(text)
+        before = content_words(previous)
+        return false if now.empty? || before.empty?
+        # A one-word follow-up is not evidence of anything.
+        return false if now.size < 3
+
+        (now & before).size.to_f / now.size >= overlap
+      end
+
+      # Enough shared vocabulary to be about the same thing, without being the
+      # same sentence. A reframing opener on an unrelated question is just a
+      # question.
+      def shares_topic?(text, previous)
+        now = content_words(text)
+        before = content_words(previous)
+        return false if now.empty? || before.empty?
+
+        now.intersect?(before)
+      end
+
+      def content_words(text)
+        text.to_s.downcase.scan(/[a-z0-9_-]{2,}/) - STOP
+      end
+
+      def user?(turn)
+        role = turn[:role] || turn['role']
+        role.nil? || role.to_sym == :user
+      end
+    end
+  end
+end

data/lib/vangrail/rails/exfiltration.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'uri'
+require_relative '../rail'
+
+module Vangrail
+  module Rails
+    # Strips outbound URLs an answer has no business emitting.
+    #
+    # This is the rail for the attack that does not need the reader to do
+    # anything. A poisoned page tells the model to end its answer with a
+    # markdown image whose URL carries the conversation in a query parameter;
+    # the chat client renders markdown, so it fetches that URL by itself, and
+    # the data is gone before anybody has read a word. The same trick with a
+    # link needs one click, which a reader who trusts the assistant will give
+    # it. Every shipped assistant that rendered markdown had this, and the fix
+    # each of them landed on was the same: decide which hosts may be fetched,
+    # and refuse the rest.
+    #
+    # So the rule here is an allowlist, and the default allowlist is empty,
+    # because a documentation assistant answering from a handbook has exactly
+    # one set of hosts worth linking to and the application knows what they are.
+    #
+    #   Rails::Exfiltration.new(allow_hosts: %w[docs.example.org example.org])
+    #
+    # Images are stricter than links: an image is fetched without consent, so a
+    # host being allowlisted for links does not make it a place to auto-load
+    # from unless `allow_images` names it too.
+    #
+    # It redacts rather than blocks. An answer with a bad link is a useful
+    # answer with one bad span in it, and throwing away the help teaches readers
+    # that the guardrail is the problem. The link text survives; the target does
+    # not.
+    class Exfiltration < Rail
+      # Kept out of prose because a bare marker in the middle of a sentence
+      # reads as an editing artefact, which is exactly what it is.
+      PLACEHOLDER = '[link removed]'
+      IMAGE_PLACEHOLDER = '[image removed]'
+
+      # Markdown image, markdown link, bare HTML img/a, and anything with an
+      # explicit scheme that is not http(s). Autolinks in angle brackets count:
+      # some renderers fetch previews for them.
+      IMAGE = /!\[([^\]]*)\]\(\s*<?([^)\s>]+)>?[^)]*\)/
+      LINK = /(?<!!)\[([^\]]*)\]\(\s*<?([^)\s>]+)>?[^)]*\)/
+      HTML_IMAGE = /<img\b[^>]*?\bsrc\s*=\s*["']?([^"'>\s]+)[^>]*>/i
+      HTML_LINK = /<a\b[^>]*?\bhref\s*=\s*["']?([^"'>\s]+)[^>]*>(.*?)<\/a>/im
+      AUTOLINK = /<((?:https?|data|file|ftp):\/\/[^>\s]+)>/i
+
+      # A URL is suspicious on its own terms when it carries a payload: a long
+      # query string, percent-encoded text, or a base64 run. An allowlisted host
+      # with a hundred characters of query is still worth naming, because that
+      # is what the exfiltration looks like when the attacker knows the
+      # allowlist.
+      PAYLOAD = /[?#].{40,}/
+      ENCODED = /(?:%[0-9A-Fa-f]{2}){6,}|[A-Za-z0-9+\/]{40,}={0,2}/
+
+      attr_reader :allow_hosts, :allow_images, :placeholder, :max_query
+
+      def initialize(allow_hosts: [], allow_images: nil, placeholder: PLACEHOLDER,
+                     max_query: 40, name: 'exfiltration', sides: [:output])
+        super(name: name, sides: sides)
+        @allow_hosts = normalise(allow_hosts)
+        # nil means "the same hosts as links". An empty array means no images at
+        # all, which is the safe reading of an application that never asked.
+        @allow_images = allow_images.nil? ? @allow_hosts : normalise(allow_images)
+        @placeholder = placeholder
+        @max_query = max_query
+      end
+
+      def offline?
+        true
+      end
+
+      def cache_key(text, _context)
+        text
+      end
+
+      def call(text, _context)
+        body = text.to_s
+        found = []
+        cleaned = strip_all(body, found)
+        return pass if found.empty?
+
+        modify(cleaned, categories: found.uniq,
+                        reason: "removed #{found.uniq.join(', ')}")
+      end
+
+      # Whether this rail would leave the URL alone. Public because a caller
+      # rendering its own links wants the same answer without a Result.
+      def allowed?(url, image: false)
+        host = host_of(url)
+        return false if host.nil?
+
+        list = image ? allow_images : allow_hosts
+        return false unless list.any? { |h| host == h || host.end_with?(".#{h}") }
+
+        !payload?(url)
+      end
+
+      private
+
+      # The whole match is passed along rather than read back from
+      # Regexp.last_match: a block shares its enclosing frame's match data, and a
+      # method called from that block has its own, so a helper reading it would
+      # see nothing.
+      def strip_all(body, found)
+        m = ->(n) { Regexp.last_match(n) }
+        out = body.gsub(IMAGE) { redact_image(m[0], m[1], m[2], found) }
+        out = out.gsub(LINK) { redact_link(m[0], m[1], m[2], found) }
+        out = out.gsub(HTML_IMAGE) { redact_image(m[0], '', m[1], found) }
+        out = out.gsub(HTML_LINK) { redact_link(m[0], m[2], m[1], found) }
+        out.gsub(AUTOLINK) { redact_link(m[0], nil, m[1], found) }
+      end
+
+      def redact_image(whole, alt, url, found)
+        return whole if allowed?(url, image: true)
+
+        found << category(url, image: true)
+        alt.to_s.empty? ? IMAGE_PLACEHOLDER : "#{alt} #{IMAGE_PLACEHOLDER}"
+      end
+
+      # The words stay, the destination goes. A reader still sees what the
+      # answer meant to point at and can search for it.
+      def redact_link(whole, label, url, found)
+        return whole if allowed?(url)
+
+        found << category(url)
+        text = label.to_s.strip
+        text.empty? ? placeholder : "#{text} #{placeholder}"
+      end
+
+      def category(url, image: false)
+        return image ? 'foreign_image' : 'foreign_link' unless payload?(url)
+
+        image ? 'image_payload' : 'link_payload'
+      end
+
+      # Long query strings and encoded runs are the payload itself. Checked
+      # before the allowlist matters, so an allowlisted host cannot be used as
+      # an open redirect for the same trick.
+      def payload?(url)
+        query = url.to_s[/[?#].*/].to_s
+        return true if query.length > max_query
+        return true if query.match?(PAYLOAD)
+
+        query.match?(ENCODED)
+      end
+
+      # Anything without a parseable http(s) host is refused, which covers
+      # data:, file:, javascript:, protocol-relative //evil, and the malformed
+      # cases a renderer might still resolve.
+      def host_of(url)
+        uri = URI.parse(url.to_s.strip)
+        return nil unless %w[http https].include?(uri.scheme)
+
+        uri.host&.downcase
+      rescue URI::InvalidURIError
+        nil
+      end
+
+      def normalise(hosts)
+        Array(hosts).map { |h| h.to_s.downcase.sub(/\Ahttps?:\/\//, '').split('/').first.to_s }
+                    .reject(&:empty?).freeze
+      end
+    end
+  end
+end