maquina_stream 0.1.0

data/lib/maquina_stream/sanitizer.rb

@@ -0,0 +1,392 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+require "uri"
+
+module MaquinaStream
+  # Allowlist plus URL hardening. The last pass before output, and it runs
+  # unconditionally.
+  #
+  # ```ruby
+  # MaquinaStream::Sanitizer.call(html, config: MaquinaStream.config) # => String
+  # ```
+  #
+  # The input is model output: hostile, prompt-injectable, and never trusted
+  # because an earlier stage already looked at it. Nothing here is a cleanup
+  # pass — an element or an attribute survives only by being named, and a URL
+  # survives only by being re-parsed and re-checked. Everything else is
+  # dropped, not escaped and kept.
+  #
+  # Renderer calls this itself, last, on every render. A host only calls it
+  # directly when it produces HTML of its own that a model had a hand in.
+  #
+  # Five configuration keys steer it — `default_origin`, `allowed_protocols`,
+  # `allowed_link_prefixes`, `allowed_image_prefixes` and `allow_data_images`.
+  # Nothing else about it is configurable: the element and attribute allowlists
+  # are constants, and widening one means editing this file with the regression
+  # suite in front of you.
+  #
+  # It is not the last line of defence either. Renderer output is sanitized
+  # *again* client-side before it reaches the DOM, because the payload came from
+  # a model and model output is prompt-injectable.
+  #
+  # See docs/security.md for what survives, what is dropped, and the known
+  # holes.
+  class Sanitizer
+    # Elements that survive: rendered markdown, plus the wrappers the post-pass
+    # adds around it.
+    ALLOWED_ELEMENTS = %w[
+      p div span br hr
+      h1 h2 h3 h4 h5 h6
+      ul ol li dl dt dd
+      table thead tbody tfoot tr td th caption colgroup col
+      pre code kbd samp var
+      blockquote figure figcaption details summary section article aside
+      a img button
+      em strong b i u s del ins mark small sub sup q abbr dfn cite time wbr
+      input
+    ].to_set.freeze
+
+    # Removed with everything inside them. Unwrapping these would smuggle their
+    # contents back into the document: script text, CSS, or a foreign-content
+    # (SVG/MathML) subtree whose parsing rules are not HTML's.
+    DROP_WITH_CONTENT = %w[
+      script style svg math template noscript iframe frame frameset object
+      embed applet param form select option optgroup textarea label
+      fieldset legend base link meta head title html body audio video source
+      track canvas map area portal dialog marquee plaintext xmp listing
+    ].to_set.freeze
+
+    # `hidden` earns its place: the raw-source carrier is a hidden <pre>, and a
+    # carrier that loses its hidden attribute renders every code block twice.
+    GLOBAL_ATTRIBUTES = %w[id class title lang dir role translate hidden].to_set.freeze
+
+    ELEMENT_ATTRIBUTES = {
+      "a" => %w[href target rel hreflang type],
+      # The component controls are buttons, so button cannot be dropped
+      # wholesale. It is allowed with a deliberately short attribute list: no
+      # `name`, `value`, `form`, `formaction` or `formmethod`, so an injected
+      # button cannot submit anything, and `type` is forced to "button" below.
+      # Behaviour still comes only from `data-action`, which is already
+      # restricted to the ms- namespace, and every ms- controller treats its own
+      # values as untrusted.
+      "button" => %w[type disabled aria-pressed aria-expanded aria-controls],
+      "img" => %w[src alt width height loading decoding],
+      "ol" => %w[start reversed type],
+      "li" => %w[value],
+      "td" => %w[colspan rowspan align valign headers scope],
+      "th" => %w[colspan rowspan align valign headers scope abbr],
+      "col" => %w[span align],
+      "colgroup" => %w[span align],
+      "table" => %w[align],
+      "input" => %w[type checked disabled],
+      "time" => %w[datetime],
+      "details" => %w[open]
+    }.transform_values { |names| names.to_set.freeze }.freeze
+
+    # The allowlist already excludes every one of these. Naming them keeps the
+    # intent across refactors and gives the regression suite something explicit
+    # to assert on.
+    FORBIDDEN_ATTRIBUTES = %w[
+      srcdoc formaction xlink:href xlink:show xlink:actuate xml:base
+      style action background dynsrc lowsrc ping http-equiv srcset usemap
+      accesskey contenteditable name
+    ].to_set.freeze
+
+    # Non-Stimulus data hooks our own partials emit.
+    STATIC_DATA_ATTRIBUTES = %w[
+      data-component data-variant data-size data-slot data-state data-side
+      data-orientation data-controller data-action data-turbo-permanent
+      data-turbo-temporary
+    ].to_set.freeze
+
+    DATA_ATTRIBUTE_SHAPE = /\Adata-[a-z0-9]+(?:-[a-z0-9]+)*\z/
+
+    # Component internals: data-code-block-part, data-shimmer-part and friends.
+    # They carry no behaviour, only styling hooks for a component's own parts.
+    COMPONENT_PART_ATTRIBUTE = /\Adata-[a-z0-9]+(?:-[a-z0-9]+)*-part\z/
+    ARIA_ATTRIBUTE_SHAPE = /\Aaria-[a-z]+\z/
+
+    # Only our own controller namespace. A host or third-party identifier
+    # arriving inside model output has no business being instantiated.
+    CONTROLLER_IDENTIFIER = /\Ams-[a-z0-9]+(?:-[a-z0-9]+)*\z/
+    ACTION_DESCRIPTOR = %r{
+      \A
+      (?:[a-zA-Z0-9:.-]+(?:@[a-z]+)?->)?
+      ms-[a-z0-9-]+\#[a-zA-Z_][a-zA-Z0-9_]*
+      (?::[a-z]+)*
+      \z
+    }x
+
+    # Rejected however they are spelled, including after the decoding a browser
+    # would do on our behalf.
+    DANGEROUS_SCHEMES = %w[
+      javascript livescript vbscript jscript mocha data file blob about jar
+      view-source chrome chrome-extension resource feed ms-its
+    ].to_set.freeze
+
+    # Control characters, and the whitespace a browser strips before it reads
+    # the scheme. Removing them first means the scheme we test is the scheme
+    # the browser will act on.
+    URL_NOISE = /[\u0000-\u0020\u007F-\u00A0\u1680\u180E\u2000-\u200F\u2028\u2029\u202F\u205F\u3000\uFEFF]/
+
+    DATA_IMAGE = %r{
+      \Adata:image/(?:png|jpe?g|gif|webp|avif|bmp|x-icon|vnd\.microsoft\.icon)
+      ;base64,[A-Za-z0-9+/=]+\z
+    }xi
+
+    class << self
+      # Sanitizes one HTML string. The usual entry point.
+      def call(html, config: MaquinaStream.config)
+        new(config: config).call(html)
+      end
+    end
+
+    # The Configuration whose URL keys this sanitizer reads.
+    attr_reader :config
+
+    # Builds a reusable sanitizer. A nil `config:` falls back to the global
+    # one rather than failing later, deep in a URL check.
+    def initialize(config: MaquinaStream.config)
+      @config = config || MaquinaStream.config
+    end
+
+    # Sanitizes `html` and returns the result as a String — a plain String, not
+    # `html_safe`: marking it is the caller's decision, and Renderer is the
+    # caller that makes it. Empty in, empty out.
+    def call(html)
+      return "" if html.nil?
+
+      source = html.to_s
+      return "" if source.empty?
+
+      fragment = parse(source)
+      scrub_children(fragment)
+      fragment.to_html
+    end
+
+    private
+      # HTML5 parsing wherever Nokogiri offers it. The HTML4 parser's error
+      # recovery is not any browser's, and a sanitizer that parses a document
+      # differently from the engine that will display it is a mutation XSS
+      # waiting for its input.
+      def parse(html)
+        if defined?(Nokogiri::HTML5)
+          Nokogiri::HTML5.fragment(html)
+        else
+          Nokogiri::HTML::DocumentFragment.parse(html)
+        end
+      end
+
+      def scrub_children(node)
+        node.children.to_a.each { |child| scrub_node(child) }
+      end
+
+      def scrub_node(node)
+        if node.element?
+          scrub_element(node)
+        elsif node.cdata?
+          # A parser artifact. Its characters are inert once they are text and
+          # the serializer escapes them.
+          node.replace(Nokogiri::XML::Text.new(node.content, node.document))
+        elsif !node.text?
+          # Comments, processing instructions, doctypes. A conditional comment
+          # is script delivery in a costume.
+          node.unlink
+        end
+      end
+
+      def scrub_element(node)
+        name = node.name.downcase
+
+        return node.unlink if DROP_WITH_CONTENT.include?(name) || foreign?(node)
+        return unwrap(node) unless ALLOWED_ELEMENTS.include?(name)
+
+        scrub_attributes(node, name)
+        return unless node.parent # an element rule may have removed the node
+
+        scrub_children(node)
+      end
+
+      # SVG and MathML subtrees arrive through foreign-content parsing rules,
+      # where `<style>` and `<annotation-xml>` re-enter HTML parsing. Nothing in
+      # rendered markdown needs either namespace.
+      def foreign?(node)
+        href = node.namespace&.href.to_s
+        href.include?("svg") || href.include?("MathML")
+      end
+
+      def unwrap(node)
+        scrub_children(node)
+        children = node.children
+        children.empty? ? node.unlink : node.replace(children)
+      end
+
+      def scrub_attributes(node, name)
+        # A button never submits. Even allowing `type` through, the only value
+        # it may hold is "button": an injected `type="submit"` inside a host
+        # form would otherwise submit it.
+        node["type"] = "button" if name == "button"
+
+        node.attribute_nodes.each do |attr|
+          attr_name = attr.name.downcase
+          qualified = attr.namespace ? "#{attr.namespace.prefix}:#{attr_name}" : attr_name
+
+          # Namespaced attributes (xlink:href, xml:base) never survive: an
+          # allowlist for them would have to be a second allowlist.
+          next attr.unlink if attr.namespace
+          next attr.unlink if FORBIDDEN_ATTRIBUTES.include?(qualified)
+          next attr.unlink unless allowed_attribute?(name, attr_name)
+
+          scrub_attribute_value(node, name, attr, attr_name)
+        end
+
+        enforce_element_rules(node, name)
+      end
+
+      def allowed_attribute?(element, attr_name)
+        return false if attr_name.start_with?("on")
+        return data_attribute?(attr_name) if attr_name.start_with?("data-")
+        return true if attr_name.match?(ARIA_ATTRIBUTE_SHAPE)
+        return true if GLOBAL_ATTRIBUTES.include?(attr_name)
+
+        ELEMENT_ATTRIBUTES.fetch(element, Set[]).include?(attr_name)
+      end
+
+      # `data-ms-*` is ours, and so is every Stimulus value, target, class,
+      # param and outlet derived from an `ms-` identifier. Anything else,
+      # a third-party controller's values included, is dropped.
+      def data_attribute?(attr_name)
+        return false unless attr_name.match?(DATA_ATTRIBUTE_SHAPE)
+        return true if attr_name.start_with?("data-ms-")
+        return true if attr_name.match?(COMPONENT_PART_ATTRIBUTE)
+
+        STATIC_DATA_ATTRIBUTES.include?(attr_name)
+      end
+
+      def scrub_attribute_value(node, name, attr, attr_name)
+        case attr_name
+        when "href", "src"
+          harden_url(node, name, attr, attr_name)
+        when "data-controller"
+          filter_tokens(attr) { |token| token.match?(CONTROLLER_IDENTIFIER) }
+        when "data-action"
+          filter_tokens(attr) { |token| token.match?(ACTION_DESCRIPTOR) }
+        when "target"
+          attr.value = "_blank" unless %w[_blank _self].include?(attr.value)
+        end
+      end
+
+      def filter_tokens(attr)
+        kept = attr.value.to_s.split(/\s+/).reject(&:empty?).select { |token| yield token }
+        kept.empty? ? attr.unlink : attr.value = kept.join(" ")
+      end
+
+      def harden_url(node, name, attr, attr_name)
+        kind = (name == "img" || attr_name == "src") ? :image : :link
+        safe = safe_url(attr.value, kind: kind)
+
+        return attr.value = safe if safe
+
+        attr.unlink
+        # An image with no source is a broken rectangle carrying an
+        # attacker-chosen alt string. A link with no href still shows its text.
+        node.unlink if name == "img"
+      end
+
+      def safe_url(raw, kind:)
+        url = raw.to_s.gsub(URL_NOISE, "")
+        return nil if url.empty?
+        return url if url.start_with?("#") # same-document fragment
+
+        # `//evil.example`, and the backslash spellings browsers normalize into
+        # it, inherit the page's scheme and none of its origin.
+        return nil if url.match?(%r{\A[\\/]{2}}) || url.start_with?("\\")
+
+        scheme = scheme_of(url)
+        decoded_scheme = scheme_of(decode(url))
+
+        # A scheme that only appears once the browser decodes (`%6Aavascript:`,
+        # `java&#115;cript:` double-encoded) is still a scheme.
+        return nil if decoded_scheme && decoded_scheme != scheme && DANGEROUS_SCHEMES.include?(decoded_scheme)
+
+        if scheme
+          return (kind == :image) ? data_image_url(url) : nil if scheme == "data"
+          return nil unless allowed_protocols.include?(scheme)
+        else
+          url = resolve(url)
+          return nil if url.nil?
+        end
+
+        allowed_prefix?(url, kind: kind) ? url : nil
+      end
+
+      def scheme_of(url)
+        match = /\A([a-zA-Z][a-zA-Z0-9+.-]*):/.match(url)
+        match && match[1].downcase
+      end
+
+      # What a browser is left with after entity decoding (the HTML parser has
+      # usually done one round already; double-encoded payloads survive it) and
+      # after percent decoding.
+      def decode(url)
+        decoded = url.gsub(/&#x([0-9a-fA-F]+);?/) { [Regexp.last_match(1).hex].pack("U") }
+        decoded = decoded.gsub(/&#(\d+);?/) { [Regexp.last_match(1).to_i].pack("U") }
+        decoded = decoded.gsub(/%([0-9a-fA-F]{2})/) { [Regexp.last_match(1)].pack("H2") }
+        decoded.force_encoding(Encoding::UTF_8).gsub(URL_NOISE, "")
+      rescue ArgumentError, RangeError
+        url
+      end
+
+      # Base64 raster images only. `data:image/svg+xml` is a scriptable
+      # document wearing an image's MIME type.
+      def data_image_url(url)
+        return nil unless allow_data_images?
+        return nil unless url.match?(DATA_IMAGE)
+
+        url
+      end
+
+      def resolve(url)
+        origin = config.default_origin
+        return url if origin.nil? || origin.to_s.empty?
+
+        joined = URI.join(origin.to_s, url).to_s
+        allowed_protocols.include?(scheme_of(joined).to_s) ? joined : nil
+      rescue URI::Error
+        nil
+      end
+
+      def allowed_prefix?(url, kind:)
+        prefixes = Array((kind == :image) ? config.allowed_image_prefixes : config.allowed_link_prefixes)
+        return true if prefixes.empty? || prefixes.include?("*")
+
+        prefixes.any? { |prefix| url.start_with?(prefix.to_s) }
+      end
+
+      def allowed_protocols
+        @allowed_protocols ||= Array(config.allowed_protocols).map { |p| p.to_s.downcase.delete_suffix(":") }
+      end
+
+      def allow_data_images?
+        !!config.allow_data_images
+      end
+
+      def enforce_element_rules(node, name)
+        case name
+        when "input"
+          # The tasklist extension's disabled checkbox, and nothing else.
+          (node["type"].to_s.downcase == "checkbox") ? node["disabled"] = "disabled" : node.unlink
+        when "a"
+          harden_link(node)
+        end
+      end
+
+      def harden_link(node)
+        return unless node["href"]
+
+        rel = node["rel"].to_s.split(/\s+/) | %w[noopener noreferrer]
+        node["rel"] = rel.reject(&:empty?).join(" ")
+      end
+  end
+end

data/lib/maquina_stream/streamable.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module MaquinaStream
+  # Host contract for a streamable record. The host owns persistence; the
+  # engine never guesses a broadcast target and never invents authorization.
+  #
+  # ```ruby
+  # class Message < ApplicationRecord
+  #   include MaquinaStream::Streamable
+  #
+  #   maquina_stream buffer: :content,
+  #                  stream_for: ->(m) { [m.conversation, :messages] }
+  # end
+  # ```
+  #
+  # The macro generates the contract methods when the column names match (see
+  # docs/streaming.md). Anything the host defines itself wins, and a
+  # method whose backing column is missing raises ContractError naming the
+  # method, the column and the class.
+  #
+  # ## What the columns must be
+  #
+  # | Method | Column it reads |
+  # |---|---|
+  # | `#maquina_stream_buffer`, `#maquina_stream_append` | whatever `buffer:` named |
+  # | `#maquina_stream_sequence`, `#maquina_stream_advance` | `stream_sequence`, an integer |
+  # | `#maquina_stream_open?`, `#maquina_stream_seal!`, `#maquina_stream_status` | `stream_status`, a string holding `open` / `complete` / `cancelled` / `errored` / `timed_out` |
+  #
+  # `#maquina_stream_id` needs no column — it is `to_param`. `#maquina_stream_target`
+  # needs none either; it calls the `stream_for:` lambda.
+  #
+  # ## The generated methods
+  #
+  # | Method | Returns |
+  # |---|---|
+  # | `#maquina_stream_id` | `String`, stable and unique per message |
+  # | `#maquina_stream_buffer` | `String`, the raw markdown written so far |
+  # | `#maquina_stream_append(text)` | the whole buffer after appending and persisting |
+  # | `#maquina_stream_sequence` | `Integer`, monotonic, one per frame that went out |
+  # | `#maquina_stream_advance` | `Integer`, the next sequence number, incremented atomically |
+  # | `#maquina_stream_open?` | `Boolean` |
+  # | `#maquina_stream_status` | the recorded end state as a Symbol, or `nil` while open |
+  # | `#maquina_stream_seal!(status: :complete)` | the status Symbol it sealed with |
+  # | `#maquina_stream_target` | the Turbo broadcast target, from `stream_for:` |
+  #
+  # Each is documented on Streamable::Generated. Defining any of them in the
+  # model body overrides the generated one — the macro `include`s a module, so
+  # the class body always wins.
+  module Streamable
+    extend ActiveSupport::Concern
+
+    # The column `#maquina_stream_sequence` and `#maquina_stream_advance` read.
+    SEQUENCE_COLUMN = :stream_sequence
+
+    # The column `#maquina_stream_open?`, `#maquina_stream_status` and
+    # `#maquina_stream_seal!` read.
+    STATUS_COLUMN = :stream_status
+
+    # The one value of STATUS_COLUMN that means the stream is still being
+    # written. Everything else is a seal.
+    OPEN_STATUS = "open"
+    # A stream that timed out is not the same as one that errored: nothing went
+    # wrong, the model simply stopped answering, and the partial text it did
+    # produce is still worth keeping and replaying.
+    SEAL_STATUSES = %i[complete cancelled errored timed_out].freeze
+
+    # Every method a host must answer to. The macro generates all of them; a
+    # host that cannot use the macro implements this list itself.
+    CONTRACT_METHODS = %i[
+      maquina_stream_id
+      maquina_stream_buffer
+      maquina_stream_append
+      maquina_stream_sequence
+      maquina_stream_advance
+      maquina_stream_open?
+      maquina_stream_seal!
+      maquina_stream_target
+    ].freeze
+
+    included do
+      class_attribute :maquina_stream_buffer_column, instance_writer: false
+      class_attribute :maquina_stream_target_resolver, instance_writer: false
+    end
+
+    class_methods do
+      # Declares this model streamable and generates the contract methods.
+      #
+      # ```ruby
+      # maquina_stream buffer: :content,
+      #                stream_for: ->(m) { [m.conversation, :messages] }
+      # ```
+      #
+      # `buffer:` names the column holding the raw markdown. `stream_for:` is a
+      # callable receiving the record and returning the Turbo broadcast target
+      # — the engine never guesses one, because who may listen to a stream is
+      # the host's question and not the engine's.
+      #
+      # The generated methods arrive through an included module, so anything
+      # the class body defines wins over them.
+      def maquina_stream(buffer:, stream_for:)
+        self.maquina_stream_buffer_column = buffer.to_sym
+        self.maquina_stream_target_resolver = stream_for
+
+        include Generated
+      end
+
+      # Names the contract methods this class cannot satisfy — the generated
+      # ones whose column is missing and that the host has not defined itself.
+      #
+      # Returns an Array of method names, empty when the contract is complete.
+      # Worth asserting in a host's own test suite: the alternative is finding
+      # out mid-stream, when the ContractError raises inside a broadcast.
+      def maquina_stream_contract_gaps
+        Generated.instance_methods.filter_map do |method|
+          column = Generated::REQUIRED_COLUMNS[method]
+          next if column.nil?
+
+          column = maquina_stream_buffer_column if column == :buffer
+          method unless maquina_stream_column?(column)
+        end
+      end
+
+      # Whether this model has the named column. Answers `false` rather than
+      # raising when the database is unreachable — the contract check must not
+      # be the thing that breaks a boot.
+      def maquina_stream_column?(column)
+        column_names.include?(column.to_s)
+      rescue ActiveRecord::StatementInvalid, ActiveRecord::NoDatabaseError
+        false
+      end
+    end
+
+    # The host contract, generated by the `maquina_stream` macro. Included, so
+    # a host method defined in the class body overrides it.
+    #
+    # These are the methods the engine calls on a record — Broadcaster,
+    # Manifest, Export and MaquinaStream.render between them use nothing else.
+    # A host that cannot use the macro implements this module's public methods
+    # itself and never includes it.
+    module Generated
+      REQUIRED_COLUMNS = {
+        maquina_stream_buffer: :buffer,
+        maquina_stream_append: :buffer,
+        maquina_stream_sequence: SEQUENCE_COLUMN,
+        maquina_stream_open?: STATUS_COLUMN,
+        maquina_stream_seal!: STATUS_COLUMN
+      }.freeze
+
+      # A stable String, unique per message, used to build every DOM id in the
+      # message and to look the record back up in a repair request. Defaults to
+      # `to_param`.
+      def maquina_stream_id
+        to_param.to_s
+      end
+
+      # The raw markdown written so far, as a String. Never HTML: the buffer is
+      # what the model wrote, and rendering it is the engine's job.
+      #
+      # Raises ContractError when the column named by `buffer:` does not exist.
+      def maquina_stream_buffer
+        maquina_stream_read(buffer_column, :maquina_stream_buffer).to_s
+      end
+
+      # Appends `text` to the buffer, persists it, and returns the whole
+      # buffer.
+      #
+      # The host owns persistence, which is why this and not the broadcaster
+      # writes. Broadcaster#append calls it first and only then has something
+      # to broadcast.
+      #
+      # Raises ContractError when the buffer column does not exist.
+      def maquina_stream_append(text)
+        column = buffer_column
+        maquina_stream_require_column!(column, :maquina_stream_append)
+        update!(column => "#{public_send(column)}#{text}")
+        maquina_stream_buffer
+      end
+
+      # The current frame sequence number, as an Integer. Monotonic. It moves
+      # once per frame that actually goes out, not once per append — the client
+      # uses it to notice that it missed one.
+      def maquina_stream_sequence
+        maquina_stream_read(SEQUENCE_COLUMN, :maquina_stream_sequence).to_i
+      end
+
+      # Increments the sequence and returns the new value.
+      #
+      # Added in Phase 3. The sequence is documented as "incremented per frame",
+      # but the Broadcaster cannot write host state directly without
+      # contradicting "host owns persistence" - so it asks, through the
+      # contract, and the host's database does the incrementing atomically.
+      # That is also what keeps it monotonic under concurrent appends.
+      def maquina_stream_advance
+        maquina_stream_require_column!(SEQUENCE_COLUMN, :maquina_stream_advance)
+        self.class.where(id: id).update_all("#{SEQUENCE_COLUMN} = #{SEQUENCE_COLUMN} + 1")
+        reload.maquina_stream_sequence
+      end
+
+      # The recorded end state as a Symbol — one of SEAL_STATUSES — for replay
+      # and export. Nil while still open.
+      #
+      # Export reads this to decide whether to append a status footer: a
+      # cancelled message that exports as though it were complete is a lie in a
+      # file somebody keeps.
+      def maquina_stream_status
+        return nil if maquina_stream_open?
+
+        maquina_stream_read(STATUS_COLUMN, :maquina_stream_status)&.to_sym
+      end
+
+      # Whether the stream is still being written.
+      #
+      # This is what decides render mode and what decides cacheability: an open
+      # message is never cached, because it is about to change.
+      def maquina_stream_open?
+        maquina_stream_read(STATUS_COLUMN, :maquina_stream_open?).to_s == OPEN_STATUS
+      end
+
+      # Closes the stream and returns the status Symbol it sealed with.
+      #
+      # `status:` must be one of SEAL_STATUSES: `:complete`, `:cancelled`,
+      # `:errored` or `:timed_out`. Anything else raises ArgumentError.
+      #
+      # Sealing only records the status. Broadcaster#seal! is what also emits
+      # the final frame, and that frame is never coalesced and never skipped —
+      # so a host seals through the broadcaster, not through this directly,
+      # unless it means to close a stream silently.
+      def maquina_stream_seal!(status: :complete)
+        unless SEAL_STATUSES.include?(status.to_sym)
+          raise ArgumentError, "status must be one of #{SEAL_STATUSES.join(", ")}, got #{status.inspect}"
+        end
+
+        maquina_stream_require_column!(STATUS_COLUMN, :maquina_stream_seal!)
+        update!(STATUS_COLUMN => status.to_s)
+        status.to_sym
+      end
+
+      # The Turbo broadcast target, from the `stream_for:` callable the macro
+      # was given. Whatever that callable returns is passed straight to
+      # `Turbo::StreamsChannel`.
+      #
+      # Raises ContractError when `stream_for:` is not callable: the broadcast
+      # target belongs to the host, and the engine never guesses one.
+      def maquina_stream_target
+        resolver = self.class.maquina_stream_target_resolver
+        unless resolver.respond_to?(:call)
+          raise ContractError, <<~MESSAGE
+            #{self.class.name} does not supply #maquina_stream_target: `stream_for:`
+            is not callable. The broadcast target belongs to the host — the engine
+            never guesses one. See docs/streaming.md.
+          MESSAGE
+        end
+
+        resolver.call(self)
+      end
+
+      private
+        def buffer_column
+          self.class.maquina_stream_buffer_column
+        end
+
+        def maquina_stream_read(column, method)
+          maquina_stream_require_column!(column, method)
+          public_send(column)
+        end
+
+        def maquina_stream_require_column!(column, method)
+          return if self.class.maquina_stream_column?(column)
+
+          raise ContractError, <<~MESSAGE
+            #{self.class.name} does not satisfy MaquinaStream::Streamable: ##{method}
+            needs a `#{column}` column, and #{self.class.name} has none. Add the column,
+            or define ##{method} on #{self.class.name} yourself.
+            See docs/streaming.md.
+          MESSAGE
+        end
+    end
+  end
+end