collavre 0.20.2 → 0.21.0

data/app/services/collavre/markdown_converter.rb

@@ -14,25 +14,38 @@ module Collavre
       # Falls back to lightweight regex conversion for short inline fragments.
       def markdown_to_html(text, image_refs = {})
         return "" if text.nil?
-        input = text.dup
 
-        # Collect reference-style data-URI images: [alt]: <data:...>
-        input.gsub!(/^\s*\[([^\]]+)\]:\s*<\s*(data:image\/[^>]+)\s*>\s*$/) do
-          image_refs[$1] = $2.strip
-          ""
-        end
+        # Protect fenced code blocks and inline code spans from the regex
+        # rewrites below — a Markdown sample like ```` ```md\n![x](data:...)\n``` ````
+        # must not silently upload its data URI as an Active Storage blob.
+        input = with_code_protected(text.dup) do |source|
+          # Collect reference-style data-URI images. CommonMark allows both the
+          # angle-bracket form `[alt]: <data:...>` and the bare form
+          # `[alt]: data:image/...`, optionally followed by a title.
+          source.gsub!(/^\s*\[([^\]]+)\]:\s*(?:<\s*(data:image\/[^>]+?)\s*>|(data:image\/\S+))\s*(?:"[^"]*"|'[^']*'|\([^)]*\))?\s*$/) do
+            image_refs[$1] = ($2 || $3).strip
+            ""
+          end
 
-        # Convert data-URI images to Active Storage before rendering
-        input.gsub!(/(?<!\\)!\[([^\]]*)\]\[([^\]]+)\]/) do
-          if (data_url = image_refs[$2])
-            data_image_to_attachment(data_url, $1)
-          else
-            "![#{$1}][#{$2}]"
+          # Convert data-URI images to Active Storage before rendering
+          source.gsub!(/(?<!\\)!\[([^\]]*)\]\[([^\]]+)\]/) do
+            if (data_url = image_refs[$2])
+              data_image_to_attachment(data_url, $1)
+            else
+              "![#{$1}][#{$2}]"
+            end
+          end
+
+          # Inline data-URI images. base64 contains no whitespace or `)`, so bound
+          # the URL on those and capture an optional CommonMark title separately;
+          # otherwise `data:...;base64,XYZ "caption"` would be slurped as one URL
+          # and fail the strict parser in `data_image_to_attachment`. Titles may be
+          # double-quoted, single-quoted, or parenthesized per CommonMark.
+          source.gsub!(/(?<!\\)!\[([^\]]*)\]\(\s*(data:image\/[^\s)]+)(?:\s+(?:"[^"]*"|'[^']*'|\([^)]*\)))?\s*\)/) do
+            data_image_to_attachment($2, $1)
           end
-        end
 
-        input.gsub!(/(?<!\\)!\[([^\]]*)\]\((data:image\/[^)]+)\)/) do
-          data_image_to_attachment($2, $1)
+          source
         end
 
         # Render with commonmarker (GFM extensions: table, strikethrough, autolink, tasklist, tagfilter)
@@ -194,8 +207,110 @@ module Collavre
         end
       end
 
+      # Rewrite data-URI image references in Markdown source to point at
+      # newly-created Active Storage blobs. Returns rewritten Markdown.
+      #
+      # Used by the inline Markdown editor to persist blob URLs in the stored
+      # `markdown_source`, so subsequent text edits around the image do not
+      # re-import the same data URI into a fresh blob on every autosave.
+      def rewrite_data_uri_images(text)
+        return text if text.nil?
+        image_refs = {}
+
+        # Protect fenced code blocks and inline code spans before rewriting —
+        # a Markdown code sample like ```` ```md\n![x](data:...)\n``` ```` must
+        # not be silently uploaded as a blob and have its source rewritten,
+        # which would corrupt the user's code snippet on every autosave.
+        with_code_protected(text.dup) do |result|
+          # Collect reference-style data-URI image definitions. CommonMark accepts
+          # both the angle-bracket form `[alt]: <data:...>` and the bare form
+          # `[alt]: data:image/...`, optionally followed by a title. Rewrite each
+          # definition to point at a freshly-uploaded blob, normalizing to the
+          # bare form (titles are dropped since blob paths cannot collide with
+          # surrounding text).
+          result.gsub!(/^(\s*\[)([^\]]+)(\]:\s*)(?:<\s*(data:image\/[^>]+?)\s*>|(data:image\/\S+))(\s*(?:"[^"]*"|'[^']*'|\([^)]*\))?\s*)$/) do
+            lead, label, mid, angle_url, bare_url, tail = $1, $2, $3, $4, $5, $6
+            data_url = (angle_url || bare_url).strip
+            blob_path = data_uri_to_blob_path(data_url)
+            image_refs[label] = blob_path
+            "#{lead}#{label}#{mid}#{blob_path}#{tail}"
+          end
+
+          # Inline data-URI images: ![alt](data:...) or ![alt](data:... "title")
+          # → ![alt](blob_path) / ![alt](blob_path "title"). Parse the title
+          # separately so it doesn't get captured into the data URL and break
+          # strict matching in `data_uri_to_blob_path`. Titles may be
+          # double-quoted, single-quoted, or parenthesized per CommonMark.
+          result.gsub!(/(?<!\\)!\[([^\]]*)\]\(\s*(data:image\/[^\s)]+)(\s+(?:"[^"]*"|'[^']*'|\([^)]*\)))?\s*\)/) do
+            alt, data_url, title = $1, $2, $3
+            "![#{alt}](#{data_uri_to_blob_path(data_url)}#{title})"
+          end
+
+          result
+        end
+      end
+
+      # Convert a data-URI to a freshly-uploaded Active Storage blob path.
+      # Returns the original URL unchanged on parse failure.
+      def data_uri_to_blob_path(data_url)
+        return data_url unless data_url =~ %r{\Adata:(image/[\w.+-]+);base64,(.+)\z}
+
+        content_type = Regexp.last_match(1)
+        data = Base64.decode64(Regexp.last_match(2))
+        ext = Mime::Type.lookup(content_type).symbol.to_s
+        filename = "import-#{SecureRandom.hex}.#{ext}"
+        blob = ActiveStorage::Blob.create_and_upload!(io: StringIO.new(data), filename: filename, content_type: content_type)
+        Rails.application.routes.url_helpers.rails_blob_url(blob, only_path: true)
+      end
+
       private
 
+      # Run a regex-rewriting block on `text` with fenced code blocks,
+      # indented code blocks, and inline code spans swapped for unique tokens,
+      # then restore the original segments in the block's return value.
+      # Prevents data-URI rewrites from touching code samples that happen to
+      # contain image syntax.
+      def with_code_protected(text)
+        segments = {}
+        index = 0
+        protected_text = text
+
+        # Fenced code blocks (``` or ~~~, indented up to 3 spaces per CommonMark).
+        # The closing fence is optional: per CommonMark, an unclosed fence runs to
+        # end-of-document, so we still need to protect its contents from rewrites.
+        protected_text.gsub!(/^([ \t]{0,3})(`{3,}|~{3,})[^\n]*(?:\n(?:[\s\S]*?\n\1\2[ \t]*(?=\n|\z)|[\s\S]*\z)|\z)/) do |match|
+          token = "\x00MDPROTECT#{index}\x00"
+          segments[token] = match
+          index += 1
+          token
+        end
+
+        # Indented code blocks: contiguous lines each starting with 4+ spaces
+        # or a tab, preceded by start-of-document or a blank line (CommonRule
+        # requirement so we don't mistake list-item continuations for code).
+        protected_text.gsub!(/(\A|\n\n+)((?:(?:[ ]{4,}|\t)[^\n]*(?:\n|\z))+)/) do
+          prefix = Regexp.last_match(1)
+          block = Regexp.last_match(2)
+          token = "\x00MDPROTECT#{index}\x00"
+          segments[token] = block
+          index += 1
+          "#{prefix}#{token}"
+        end
+
+        # Inline single-backtick code spans. Multi-backtick spans are rare in
+        # practice; the protection above already covers fenced samples.
+        protected_text.gsub!(/`[^`\n]+?`/) do |match|
+          token = "\x00MDPROTECT#{index}\x00"
+          segments[token] = match
+          index += 1
+          token
+        end
+
+        rewritten = yield(protected_text)
+        segments.each { |token, original| rewritten.sub!(token, original) }
+        rewritten
+      end
+
       def escape_table_cell(text)
         text.to_s.gsub(/(?<!\\)\|/, '\\|')
       end

data/app/services/collavre/markdown_importer.rb

@@ -6,9 +6,14 @@ module Collavre
     def self.import(content, parent:, user:, create_root: false)
       lines = content.to_s.lines
       image_refs = {}
+      # CommonMark allows both the angle-bracket form `[alt]: <data:...>` and
+      # the bare form `[alt]: data:image/...`, optionally followed by a title
+      # (`"..."`, `'...'`, or `(...)`). Match both so reference-style data-URI
+      # images survive the import path and resolve to attachments downstream
+      # (mirrors MarkdownConverter#markdown_to_html).
       lines.reject! do |ln|
-        if ln =~ /^\s*\[([^\]]+)\]:\s*<\s*(data:image\/[^>]+)\s*>\s*$/
-          image_refs[$1] = $2.strip
+        if ln =~ /^\s*\[([^\]]+)\]:\s*(?:<\s*(data:image\/[^>]+?)\s*>|(data:image\/\S+))\s*(?:"[^"]*"|'[^']*'|\([^)]*\))?\s*$/
+          image_refs[$1] = ($2 || $3).strip
           true
         else
           false

data/app/services/collavre/orchestration/policy_resolver.rb

@@ -88,6 +88,8 @@ module Collavre
 
       # Convenience methods
       def arbitration_strategy
+        return "primary_first" if topic_primary_agent_id.present?
+
         arbitration_config["strategy"]
       end
 
@@ -96,7 +98,7 @@ module Collavre
       end
 
       def primary_agent_id
-        arbitration_config["primary_agent_id"]
+        topic_primary_agent_id || arbitration_config["primary_agent_id"]
       end
 
       # Bid strategy specific
@@ -160,6 +162,14 @@ module Collavre
 
         config
       end
+
+      # Read primary_agent_id directly from the topics table
+      def topic_primary_agent_id
+        topic_id = @context.dig("topic", "id")
+        return nil unless topic_id
+
+        Topic.where(id: topic_id).pick(:primary_agent_id)
+      end
     end
   end
 end

data/app/services/collavre/tools/creative_attach_files_service.rb

@@ -0,0 +1,96 @@
+module Collavre
+require "sorbet-runtime"
+require "rails_mcp_engine"
+module Tools
+  class CreativeAttachFilesService
+    extend T::Sig
+    extend ToolMeta
+    include Collavre::PublicAssetsHelper
+
+    tool_name "creative_attach_files_service"
+    tool_description "Attach one or more local files (images, video, documents) to a Creative. Files are uploaded to ActiveStorage (S3) and served publicly via CloudFront-cached /public-assets URLs.\n\nUse this to:\n- Upload landing page assets (hero images, demo videos)\n- Attach reference documents to a task\n\nFile paths must live under the configured upload root (MCP_UPLOAD_ROOT, default tmp/mcp_uploads under Rails.root). Paths outside that root are rejected.\n\nRequires :write permission on the target Creative."
+
+    tool_param :creative_id, description: "ID of the Creative to attach files to.", required: true
+    tool_param :file_paths, description: "Absolute local file paths to upload. Each path must resolve to a regular file under the upload root (MCP_UPLOAD_ROOT). If any path is missing or escapes the upload root, the entire call fails atomically.", required: true
+
+    sig { params(creative_id: Integer, file_paths: T::Array[String]).returns(T::Hash[Symbol, T.untyped]) }
+    def call(creative_id:, file_paths:)
+      raise "Current.user is required" unless Current.user
+
+      creative = Creative.find_by(id: creative_id)
+      return { error: "Creative not found", id: creative_id } unless creative
+
+      unless creative.has_permission?(Current.user, :write)
+        return { error: "No write permission on Creative", id: creative_id }
+      end
+
+      root = self.class.upload_root
+      resolved = []
+      missing = []
+      outside = []
+      file_paths.each do |raw|
+        begin
+          real = File.realpath(raw)
+        rescue Errno::ENOENT, Errno::ENOTDIR, Errno::EACCES
+          missing << raw
+          next
+        end
+        unless File.file?(real)
+          missing << raw
+          next
+        end
+        if path_under?(real, root)
+          resolved << real
+        else
+          outside << raw
+        end
+      end
+
+      return { error: "Missing files", missing: missing } if missing.any?
+      return { error: "Files outside upload root", upload_root: root.to_s, outside: outside } if outside.any?
+
+      attached = []
+      ActiveRecord::Base.transaction do
+        resolved.each do |path|
+          File.open(path, "rb") do |io|
+            creative.files.attach(
+              io: io,
+              filename: File.basename(path),
+              content_type: Marcel::MimeType.for(Pathname.new(path)) || "application/octet-stream"
+            )
+          end
+        end
+        creative.save!
+        attached = creative.files.last(resolved.length)
+      end
+
+      {
+        success: true,
+        creative_id: creative.id,
+        attachments: attached.map { |a|
+          {
+            signed_id: a.blob.signed_id,
+            filename: a.filename.to_s,
+            content_type: a.content_type,
+            byte_size: a.byte_size,
+            url: public_asset_url(a.blob)
+          }
+        }
+      }
+    end
+
+    def self.upload_root
+      raw = Collavre::IntegrationSettings.fetch(:mcp_upload_root, default: Rails.root.join("tmp/mcp_uploads").to_s)
+      Pathname.new(File.expand_path(raw)).tap do |p|
+        FileUtils.mkdir_p(p) unless p.exist?
+      end.realpath
+    end
+
+    private
+
+    def path_under?(path, root)
+      Pathname.new(path).ascend.any? { |p| p == root }
+    end
+  end
+end
+end

data/app/services/collavre/tools/creative_list_attachments_service.rb

@@ -0,0 +1,42 @@
+module Collavre
+require "sorbet-runtime"
+require "rails_mcp_engine"
+module Tools
+  class CreativeListAttachmentsService
+    extend T::Sig
+    extend ToolMeta
+    include Collavre::PublicAssetsHelper
+
+    tool_name "creative_list_attachments_service"
+    tool_description "List all attachments on a Creative with public URLs, filenames, content types, and sizes. Requires :read permission."
+
+    tool_param :creative_id, description: "ID of the Creative.", required: true
+
+    sig { params(creative_id: Integer).returns(T::Hash[Symbol, T.untyped]) }
+    def call(creative_id:)
+      raise "Current.user is required" unless Current.user
+
+      creative = Creative.find_by(id: creative_id)
+      return { error: "Creative not found", id: creative_id } unless creative
+
+      unless creative.has_permission?(Current.user, :read)
+        return { error: "No read permission on Creative", id: creative_id }
+      end
+
+      {
+        success: true,
+        creative_id: creative.id,
+        attachments: creative.files.with_all_variant_records.map { |a|
+          {
+            signed_id: a.blob.signed_id,
+            filename: a.filename.to_s,
+            content_type: a.content_type,
+            byte_size: a.byte_size,
+            url: public_asset_url(a.blob)
+          }
+        }
+      }
+    end
+  end
+end
+end

data/app/services/collavre/tools/creative_remove_attachment_service.rb

@@ -0,0 +1,35 @@
+module Collavre
+require "sorbet-runtime"
+require "rails_mcp_engine"
+module Tools
+  class CreativeRemoveAttachmentService
+    extend T::Sig
+    extend ToolMeta
+
+    tool_name "creative_remove_attachment_service"
+    tool_description "Remove a single attachment from a Creative by its signed_id. Requires :write permission. The underlying blob is purged asynchronously."
+
+    tool_param :creative_id, description: "ID of the Creative.", required: true
+    tool_param :signed_id, description: "signed_id of the blob (from creative_list_attachments_service or creative_attach_files_service response).", required: true
+
+    sig { params(creative_id: Integer, signed_id: String).returns(T::Hash[Symbol, T.untyped]) }
+    def call(creative_id:, signed_id:)
+      raise "Current.user is required" unless Current.user
+
+      creative = Creative.find_by(id: creative_id)
+      return { error: "Creative not found", id: creative_id } unless creative
+
+      unless creative.has_permission?(Current.user, :write)
+        return { error: "No write permission on Creative", id: creative_id }
+      end
+
+      blob = ActiveStorage::Blob.find_signed(signed_id)
+      attachment = blob && creative.files.attachments.find_by(blob_id: blob.id)
+      return { error: "Attachment not found on this Creative" } unless attachment
+
+      attachment.purge_later
+      { success: true, creative_id: creative.id, removed_signed_id: signed_id }
+    end
+  end
+end
+end

data/app/services/collavre/tools/permission_denied_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Collavre
+  module Tools
+    # Raised by tool services when the current user lacks the required
+    # creative-level permission to perform a mutating action.
+    class PermissionDeniedError < StandardError; end
+  end
+end

data/app/services/collavre/tools/preview_attach_service.rb

@@ -0,0 +1,128 @@
+module Collavre
+require "sorbet-runtime"
+require "rails_mcp_engine"
+module Tools
+  # Attach a development-preview chip to a topic. AI Agents call this after
+  # spinning up `./bin/dev` against a worktree so the preview URL and run
+  # state surface as a chip in the typing-indicator row. Idempotent by
+  # (topic_id, worktree_id).
+  class PreviewAttachService
+    extend T::Sig
+    extend ToolMeta
+
+    tool_name "preview_attach"
+    tool_description <<~DESC.strip
+      Attach a development preview server to a Collavre topic. Renders a
+      chip in the topic's typing-indicator row with a clickable link to the
+      preview URL and a state badge (running/stopped). Call this after
+      starting a preview server (e.g. ./bin/dev on a worktree). Idempotent
+      per (topic_id, worktree_id) — calling twice does not duplicate the
+      chip or re-announce.
+    DESC
+
+    tool_param :topic_id, description: "The Collavre topic id to attach the preview chip to."
+    tool_param :preview_url, description: "Full URL of the preview server, e.g. http://localhost:4001"
+    tool_param :worktree_id, description: "Stable identifier for the worktree (or environment) running this preview. Used as the dedup key — re-calling with the same worktree_id reactivates the existing chip instead of creating a duplicate."
+    tool_param :label, description: "Optional display label shown on the chip. Defaults to a localized 'Preview' string.", required: false
+
+    sig do
+      params(
+        topic_id: Integer,
+        preview_url: String,
+        worktree_id: String,
+        label: T.nilable(String)
+      ).returns(T::Hash[Symbol, T.untyped])
+    end
+    def call(topic_id:, preview_url:, worktree_id:, label: nil)
+      validate_preview_url!(preview_url)
+
+      topic = Collavre::Topic.find(topic_id)
+      Collavre::Tools::TopicAuthorizer.authorize_write!(topic)
+
+      refresh_config = ->(c) {
+        # Re-attach against the same worktree may carry a fresh URL/label
+        # (e.g. port reassignment after a restart). Refresh the persisted
+        # config so the chip link goes to the live server, not the dead one
+        # — applies both when reactivating a stopped chip and when the chip
+        # is still active (:noop), which is the common dev-restart case.
+        new_config = c.config.merge(
+          "preview_url" => preview_url,
+          "preview_state" => "running"
+        )
+        new_config["label"] = label if label
+        c.config = new_config
+        # Also refresh the cached chip fields that record_event! seeded on the
+        # first attach. The chip partial renders latest_link.presence ||
+        # default_link, so without this update a :noop reattach with a new port
+        # leaves the chip pointing at the dead URL even though config is fresh.
+        # (On :reactivate the subsequent inject_into_topic! would overwrite
+        # these via record_event! anyway, so updating here is harmless.)
+        c.latest_link = preview_url
+        c.latest_label = c.default_label
+      }
+
+      channel, status = Collavre::ChannelAttacher.call(
+        channel_class: Collavre::PreviewChannel,
+        lookup: -> { lookup_channel(topic, worktree_id) },
+        create_attrs: {
+          topic_id: topic.id,
+          config: {
+            "worktree_id" => worktree_id,
+            "preview_url" => preview_url,
+            "preview_state" => "running",
+            "label" => label
+          }.compact
+        },
+        on_reactivate: refresh_config,
+        on_noop: refresh_config
+      )
+
+      # Mirror PR-channel UX: only the first attach (and a true reactivation
+      # from stopped/dismissed) announces in the topic. Subsequent idempotent
+      # attaches stay silent so frequent restarts do not spam the timeline.
+      if status == :created || status == :reactivated
+        channel.inject_into_topic!(channel.attached_message)
+      end
+
+      {
+        ok: true,
+        channel_id: channel.id,
+        worktree_id: worktree_id,
+        preview_url: preview_url,
+        status: status
+      }
+    end
+
+    private
+
+    ALLOWED_PREVIEW_URL_SCHEMES = %w[http https].freeze
+    private_constant :ALLOWED_PREVIEW_URL_SCHEMES
+
+    # The preview_url is rendered directly as the chip's <a href> via ERB,
+    # which escapes quotes but does NOT reject dangerous URL schemes. Without
+    # this gate a write-capable MCP caller could persist `javascript:...` or
+    # `data:...` and turn the chip into a one-click XSS for any topic viewer.
+    sig { params(preview_url: String).void }
+    def validate_preview_url!(preview_url)
+      uri = URI.parse(preview_url)
+      unless ALLOWED_PREVIEW_URL_SCHEMES.include?(uri.scheme&.downcase)
+        raise ArgumentError, "preview_url must be http(s); got: #{preview_url.inspect}"
+      end
+      raise ArgumentError, "preview_url must include a host" if uri.host.to_s.empty?
+    rescue URI::InvalidURIError
+      raise ArgumentError, "preview_url is not a valid URI: #{preview_url.inspect}"
+    end
+
+    # config is JSON, so worktree_id matching is a Ruby-side scan over the
+    # topic's preview channels. With only a handful of previews per topic in
+    # practice this is fine and avoids JSON operator divergence between
+    # Postgres (config->>'worktree_id') and SQLite (json_extract).
+    sig { params(topic: Collavre::Topic, worktree_id: String).returns(T.nilable(Collavre::PreviewChannel)) }
+    def lookup_channel(topic, worktree_id)
+      Collavre::PreviewChannel.where(topic_id: topic.id).find do |c|
+        c.worktree_id.to_s == worktree_id.to_s
+      end
+    end
+  end
+end
+end

data/app/services/collavre/tools/preview_detach_service.rb

@@ -0,0 +1,61 @@
+module Collavre
+require "sorbet-runtime"
+require "rails_mcp_engine"
+module Tools
+  # Mark a previously-attached preview as stopped. AI Agents call this
+  # immediately before killing the preview server (per the worktree cleanup
+  # workflow) so the chip flips to the "stopped" badge with reduced opacity.
+  # The chip stays visible until the user dismisses it with the X button —
+  # mirrors the PR-channel post-close UX where the closed badge persists for
+  # context.
+  class PreviewDetachService
+    extend T::Sig
+    extend ToolMeta
+
+    tool_name "preview_detach"
+    tool_description <<~DESC.strip
+      Mark a development preview as stopped. The chip stays visible with a
+      stopped badge until the user dismisses it. Idempotent — calling on an
+      already-stopped or missing channel returns ok with status :noop.
+    DESC
+
+    tool_param :topic_id, description: "The Collavre topic id the preview was attached to."
+    tool_param :worktree_id, description: "The worktree_id used when the preview was attached."
+
+    sig do
+      params(
+        topic_id: Integer,
+        worktree_id: String
+      ).returns(T::Hash[Symbol, T.untyped])
+    end
+    def call(topic_id:, worktree_id:)
+      topic = Collavre::Topic.find(topic_id)
+      Collavre::Tools::TopicAuthorizer.authorize_write!(topic)
+
+      channel = lookup_channel(topic, worktree_id)
+      return { ok: true, status: :noop, worktree_id: worktree_id } if channel.nil?
+
+      status =
+        if channel.preview_state == "stopped" && channel.detached?
+          :noop
+        else
+          channel.preview_state = "stopped"
+          channel.state = :detached unless channel.detached?
+          channel.save!
+          :stopped
+        end
+
+      { ok: true, channel_id: channel.id, worktree_id: worktree_id, status: status }
+    end
+
+    private
+
+    sig { params(topic: Collavre::Topic, worktree_id: String).returns(T.nilable(Collavre::PreviewChannel)) }
+    def lookup_channel(topic, worktree_id)
+      Collavre::PreviewChannel.where(topic_id: topic.id).find do |c|
+        c.worktree_id.to_s == worktree_id.to_s
+      end
+    end
+  end
+end
+end

data/app/services/collavre/tools/topic_authorizer.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Collavre
+  module Tools
+    # Topic write authorization for MCP tool services. Mirrors
+    # CreativePermissionGuard#require_creative_write! but is callable outside a
+    # controller request. Attaching a channel injects external messages into a
+    # topic, so it is a write-equivalent mutation — restrict to users with
+    # write permission on the topic's effective_origin creative.
+    module TopicAuthorizer
+      module_function
+
+      def authorize_write!(topic, user: Collavre::Current.user)
+        creative = topic.creative&.effective_origin
+        raise ArgumentError, "Topic has no creative" unless creative
+        return if creative.user == user
+        return if user && creative.has_permission?(user, :write)
+
+        raise Collavre::Tools::PermissionDeniedError,
+          "No write permission on topic #{topic.id}"
+      end
+    end
+  end
+end