labimotion 2.3.0 → 2.4.0.rc11

data/lib/labimotion/libs/ai_egress_guard.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'resolv'
+require 'ipaddr'
+require 'uri'
+
+module Labimotion
+  # Validates a USER-SUPPLIED AI provider base URL before the server makes an
+  # outbound request to it, to prevent SSRF. A user may point the AI feature at
+  # their own OpenAI-compatible endpoint, but only at a PUBLIC https host — never
+  # at loopback / private / link-local / cloud-metadata addresses.
+  #
+  # Known limitation: validation resolves DNS at check time; a hostile resolver
+  # could rebind between this check and the actual request (TOCTOU). Redirect
+  # following is disabled at the HTTP layer, which removes the most common bypass;
+  # pinning the connection to the validated IP would close the residual window.
+  class AiEgressGuard
+    class BlockedError < StandardError; end
+
+    # Ranges Ruby's IPAddr#private?/#loopback?/#link_local? don't all cover:
+    # unspecified, CGNAT, benchmarking/test-net, IPv4-broadcast, reserved,
+    # and the IPv6 unique-local / link-local / multicast blocks.
+    EXTRA_BLOCKED = [
+      '0.0.0.0/8', '100.64.0.0/10', '192.0.0.0/24', '192.0.2.0/24',
+      '198.18.0.0/15', '198.51.100.0/24', '203.0.113.0/24', '240.0.0.0/4',
+      '255.255.255.255/32', '::/128', '::1/128', 'fc00::/7', 'fe80::/10', 'ff00::/8'
+    ].map { |cidr| IPAddr.new(cidr) }.freeze
+
+    # Raise BlockedError unless url is a public https endpoint (http is also
+    # accepted outside production, e.g. against a local dev provider). Returns url.
+    def self.validate!(url)
+      uri = parse(url)
+      allowed_schemes = Rails.env.production? ? %w[https] : %w[https http]
+      raise BlockedError, "AI provider URL must use #{allowed_schemes.join(' or ')}" unless
+        allowed_schemes.include?(uri.scheme)
+
+      host = uri.host.to_s
+      raise BlockedError, 'AI provider URL has no host' if host.empty?
+
+      addresses = resolve(host)
+      raise BlockedError, "AI provider host could not be resolved: #{host}" if addresses.empty?
+
+      blocked = addresses.find { |ip| !allowed_ip?(ip) }
+      raise BlockedError, "AI provider host resolves to a non-public address (#{blocked})" if blocked
+
+      url
+    end
+
+    def self.parse(url)
+      URI.parse(url.to_s.strip)
+    rescue URI::InvalidURIError
+      raise BlockedError, 'AI provider URL is not a valid URL'
+    end
+
+    # All A/AAAA addresses for host as IPAddr; a literal IP resolves to itself.
+    def self.resolve(host)
+      return [IPAddr.new(host)] if literal_ip?(host)
+
+      Resolv.getaddresses(host).filter_map { |addr| safe_ipaddr(addr) }
+    rescue StandardError
+      []
+    end
+
+    def self.literal_ip?(str)
+      IPAddr.new(str)
+      true
+    rescue IPAddr::InvalidAddressError
+      false
+    end
+
+    def self.safe_ipaddr(addr)
+      ip = IPAddr.new(addr.to_s)
+      ip.ipv4_mapped? ? ip.native : ip
+    rescue StandardError
+      nil
+    end
+
+    # Public = not loopback/private/link-local and not in EXTRA_BLOCKED.
+    def self.public_ip?(ip)
+      return false if ip.loopback? || ip.private? || ip.link_local?
+
+      EXTRA_BLOCKED.none? { |net| net.include?(ip) }
+    rescue StandardError
+      false
+    end
+
+    # Outside production, a private-network address (e.g. a self-hosted model
+    # on another machine on the LAN) is allowed; loopback/link-local/other
+    # EXTRA_BLOCKED ranges (cloud metadata etc.) stay blocked regardless of env.
+    def self.allowed_ip?(ip)
+      return public_ip?(ip) if Rails.env.production?
+      return false if ip.loopback? || ip.link_local?
+
+      EXTRA_BLOCKED.none? { |net| net.include?(ip) }
+    rescue StandardError
+      false
+    end
+  end
+end

data/lib/labimotion/libs/ai_klass_queue.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Labimotion
+  # Hands AI template generation to the host's background worker.
+  #
+  # Generating a template is one long provider call — 18s for a small segment,
+  # past 90s for a large one — and running it inside the request held the dialog
+  # open for all of it, losing the work if the tab was closed or reloaded. The
+  # endpoints enqueue instead and answer at once; the result comes back as a
+  # notification carrying a link into the designer.
+  #
+  # The job itself belongs to the host: ActiveJob, the queue and the Message
+  # machinery are all its, and a gem that shipped its own would be defining
+  # infrastructure it does not own. So the host class is reached by its bare
+  # name and only if it exists — the same NameError-guarded pattern used for
+  # Matrice and Message elsewhere in this gem. A host without it gets the old
+  # inline behaviour rather than an error, which is what `queue` returning false
+  # tells the caller.
+  module AiKlassQueue
+    JOB = 'AiTemplateJob'
+
+    # @return [Boolean] true when the work was handed off
+    def self.queue(kind:, params:, user:, element_klass_id: nil)
+      job = job_class
+      return false if job.nil?
+
+      # Grape params are a Hashie::Mash; the queue serialises what it is given,
+      # and a Mash carries method_missing behaviour a worker process should not
+      # be asked to rebuild. A plain hash is the whole contract.
+      args = [kind.to_s, plain(params), user.id, element_klass_id]
+      inline? ? run_now(job, args, user) : job.perform_later(*args)
+      true
+    rescue StandardError => e
+      # An enqueue that fails must not fail the request: the caller falls back
+      # to generating inline, which is slower but still correct.
+      Labimotion.log_exception(e, user)
+      false
+    end
+
+    # Queued in every environment, development included: one code path, and the
+    # request returns straight away wherever it runs. Development therefore
+    # needs a worker like anywhere else — without one the job sits in the table
+    # and the notification never arrives.
+    #
+    # LABIMOTION_AI_INLINE=true runs it in the request instead, for a machine
+    # with no worker to spare. Off unless asked for, because a create that
+    # blocks for the length of a provider call is not the behaviour anyone
+    # should get by accident.
+    def self.inline?
+      ENV['LABIMOTION_AI_INLINE'] == 'true'
+    rescue StandardError
+      false
+    end
+
+    # Deliberately swallows: the job reports its own failure as a notification,
+    # exactly as it would on a worker, and letting it raise here would send the
+    # caller down the inline-generation fallback — spending a second provider
+    # call on work that has already been done and paid for.
+    def self.run_now(job, args, user)
+      job.perform_now(*args)
+    rescue StandardError => e
+      Labimotion.log_exception(e, user)
+      nil
+    end
+
+    def self.job_class
+      Object.const_get(JOB)
+    rescue NameError
+      nil
+    end
+
+    # Only what the helpers read, and stringified: file payloads included, since
+    # the reference files are part of the request the worker has to replay.
+    #
+    # A JSON round trip rather than as_json, because that is precisely what the
+    # queue will do to these arguments anyway — so anything that would not
+    # survive being written to the jobs table fails here, in the request, rather
+    # than in a worker nobody is watching.
+    def self.plain(params)
+      return {} if params.nil?
+
+      source = params.respond_to?(:to_unsafe_h) ? params.to_unsafe_h : params
+      JSON.parse(JSON.generate(source))
+    end
+  end
+end

data/lib/labimotion/libs/ai_klass_validator.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Labimotion
+  # The checks that must happen BEFORE a template is generated.
+  #
+  # Generation moved to a background job, and the cheap objections — this name
+  # is taken, this ontology term already has a template — used to live inside
+  # the create helpers, which now run inside that job. So the user spent a
+  # provider call and 15-90s of waiting only to be told the label was already in
+  # use, which was knowable before a single token was spent. Worse, the answer
+  # arrived as a notification long after the dialog that could have fixed it had
+  # closed.
+  #
+  # These are only the objections that can be settled by a lookup. Anything the
+  # model decides at create! stays there: this is a courtesy gate, not a second
+  # source of truth, and the create still validates for real.
+  module AiKlassValidator
+    # @return [String, nil] the objection, or nil when there is none
+    def self.error_for(kind:, params:, element_klass: nil)
+      files = file_error(params)
+      return files if files
+
+      case kind.to_s
+      when 'element' then element_error(params)
+      when 'segment' then segment_error(params, element_klass)
+      when 'dataset' then dataset_error(params)
+      end
+    end
+
+    def self.file_error(params)
+      count = Array(params[:files]).size
+      return nil if count <= Labimotion::AiTemplate::MAX_FILES
+
+      "Too many files (max #{Labimotion::AiTemplate::MAX_FILES})."
+    end
+
+    # Mirrors ElementKlass's `validates :name, uniqueness:` — scoped to rows that
+    # are not soft-deleted, so a deleted template does not block the name it no
+    # longer holds.
+    def self.element_error(params)
+      name = params[:name].to_s.strip
+      return 'A name is required.' if name.blank?
+      return 'A label is required.' if params[:label].to_s.strip.blank?
+
+      return unless Labimotion::ElementKlass.where(deleted_at: nil).exists?(name: name)
+
+      "An element named [#{name}] already exists."
+    end
+
+    # Mirrors SegmentKlass's `validates :label, uniqueness: { scope: :element_klass_id }`.
+    # The label only has to be unique WITHIN its parent element, which is why the
+    # parent has to be known before this can be answered at all.
+    def self.segment_error(params, element_klass)
+      label = params[:label].to_s.strip
+      return 'A label is required.' if label.blank?
+      return 'A parent element is required.' if element_klass.nil?
+
+      taken = Labimotion::SegmentKlass.where(deleted_at: nil)
+                                      .exists?(label: label, element_klass_id: element_klass.id)
+      return unless taken
+
+      "A segment template labelled [#{label}] already exists for this element."
+    end
+
+    def self.dataset_error(params)
+      term = params[:ols_term_id].to_s.split('|').first.to_s.strip
+      return 'An ontology term (CHMO) is required.' if term.blank?
+
+      return unless Labimotion::DatasetKlass.where(deleted_at: nil).exists?(ols_term_id: term)
+
+      "A dataset template already exists for #{term}. Edit it in the designer instead."
+    end
+  end
+end

data/lib/labimotion/libs/ai_models.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Labimotion
+  # Fetches the LIVE model catalogue from an OpenAI-compatible AI provider (the KIT
+  # KI-Toolbox, https://ki-toolbox.scc.kit.edu, by default) using the user's OWN API
+  # key. "My LabIMotion" offers the result in its model dropdown, so a user does not
+  # depend on the static pick-list in config/labimotion_ai.yml (:models), which goes
+  # stale whenever the provider changes its line-up.
+  #
+  # Only a PERSONAL key is ever used here: the shared server key must never be sent
+  # to a user-supplied provider URL, and a keyless user's choice is restricted to the
+  # admin allowlist anyway (Chemotion::ProfileAPI#labimotion_ai_admin_model_ids), so
+  # there would be nothing for them to pick out of a live list.
+  #
+  # Endpoint resolution mirrors Labimotion::AiTemplate: a personal :base_url (and
+  # :api_path) is honored only alongside a personal key and is SSRF-validated by
+  # Labimotion::AiEgressGuard before any request; otherwise the server-wide config
+  # applies.
+  #
+  # @example
+  #   Labimotion::AiModels.new(api_key: key).call
+  #   # => { models: [{ id: 'azure.gpt-4.1-mini', label: 'GPT-4.1 mini' }, ...],
+  #   #      endpoint: 'https://ki-toolbox.scc.kit.edu/api/v1/models' }
+  class AiModels
+    # Raised with a message meant for the user (the API forwards it verbatim).
+    class Error < StandardError; end
+
+    DEFAULT_BASE_URL = 'https://ki-toolbox.scc.kit.edu'
+    DEFAULT_API_PATH = '/api/v1/chat/completions'
+    # List endpoints tried after the one derived from the configured chat-completions
+    # path: Open WebUI (what KI-Toolbox runs) serves /api/models, the OpenAI standard
+    # is /v1/models. The first that answers with a usable list wins.
+    FALLBACK_PATHS = ['/api/models', '/v1/models', '/api/v1/models'].freeze
+    REQUEST_TIMEOUT = 20
+
+    # Model ids/names that are not chat models. KI-Toolbox lists embedding, reranking,
+    # speech and image models next to the chat ones; offering those in the dropdown
+    # would only produce puzzling failures when a template is generated.
+    NON_CHAT_PATTERN = /
+      embed | rerank | whisper | \btts\b | \bstt\b | flux | stable-?diffusion |
+      dall-?e | \bbge\b | moderation
+    /xi
+
+    # A provider answering these has a working endpoint but not the caller's key.
+    UNAUTHORIZED_CODES = [401, 403].freeze
+
+    MISSING_KEY_ERROR = 'Add your personal API key first — the model list is fetched with your own key.'
+
+    def initialize(api_key:, base_url: nil, api_path: nil)
+      @api_key = api_key.to_s.strip
+      @base_url_override = base_url.to_s.strip.presence
+      @api_path_override = api_path.to_s.strip.presence
+    end
+
+    # @return [Hash] { models: [{ id:, label: }], endpoint: String }
+    # @raise [Error] with a user-facing message when no list could be read
+    def call
+      raise Error, MISSING_KEY_ERROR if @api_key.blank?
+
+      statuses = {}
+      candidate_paths.each do |path|
+        url = "#{base_url}#{path}"
+        response = get(url)
+        statuses[path] = response&.code
+        models = parse_models(response)
+        return { models: models, endpoint: url } if models.present?
+      end
+      raise Error, failure_message(statuses)
+    end
+
+    private
+
+    def get(url)
+      HTTParty.get(
+        url,
+        headers: { 'Authorization' => "Bearer #{@api_key}", 'Accept' => 'application/json' },
+        timeout: REQUEST_TIMEOUT,
+        # Never follow redirects: a public URL that 302s to an internal address is the
+        # classic SSRF bypass of the egress guard.
+        follow_redirects: false
+      )
+    rescue StandardError => e
+      @network_error = e.message
+      nil
+    end
+
+    # The provider's models, or nil when this response is not a usable list.
+    def parse_models(response)
+      return nil unless response&.code == 200
+
+      body = json_body(response)
+      entries =
+        case body
+        when Array then body
+        when Hash then body['data'] || body['models']
+        end
+      # A provider may answer 200 with something else entirely (an HTML login page,
+      # an object where a list was expected): treat that as "no list here".
+      entries.is_a?(Array) ? normalize(entries) : nil
+    end
+
+    def json_body(response)
+      body = response.parsed_response
+      body.is_a?(String) ? JSON.parse(body) : body
+    rescue StandardError
+      nil
+    end
+
+    def normalize(entries)
+      entries
+        .filter_map { |entry| normalize_entry(entry) }
+        .select { |model| chat_model?(model) }
+        .uniq { |m| m[:id] }
+        .sort_by { |m| m[:label].downcase }
+    end
+
+    # An entry is either an id String or a Hash carrying at least an id.
+    def normalize_entry(entry)
+      id, label = entry.is_a?(Hash) ? hash_entry(entry) : [entry, nil]
+      id = id.to_s.strip
+      return nil if id.blank?
+
+      { id: id, label: label.to_s.strip.presence || id }
+    end
+
+    # [id, label] out of an OpenAI (id only) or Open WebUI (id + display name) entry.
+    def hash_entry(entry)
+      [entry['id'] || entry['name'] || entry['model'],
+       entry['name'] || entry['label'] || entry.dig('info', 'name')]
+    end
+
+    def chat_model?(model)
+      !(model[:id].match?(NON_CHAT_PATTERN) || model[:label].match?(NON_CHAT_PATTERN))
+    end
+
+    # True when the caller brought a provider URL on top of the personal key (which
+    # #call already requires): only then is the user endpoint honored, so the server
+    # key can never reach a user URL — same rule as Labimotion::AiTemplate.
+    def custom_endpoint?
+      @base_url_override.present?
+    end
+
+    def base_url
+      @base_url ||=
+        if custom_endpoint?
+          Labimotion::AiEgressGuard.validate!(@base_url_override)
+        else
+          setting(:base_url, 'KI_TOOLBOX_BASE_URL', DEFAULT_BASE_URL)
+        end.to_s.chomp('/')
+    end
+
+    # The list path derived from the chat-completions path first
+    # (/api/v1/chat/completions -> /api/v1/models), then the well-known fallbacks.
+    def candidate_paths
+      derived = chat_path.sub(%r{/chat/completions/?\z}, '/models')
+      ([derived] + FALLBACK_PATHS).filter_map { |path| normalize_path(path) }.uniq
+    end
+
+    def normalize_path(path)
+      path = path.to_s.strip
+      return nil if path.blank?
+
+      path.start_with?('/') ? path : "/#{path}"
+    end
+
+    def chat_path
+      return @api_path_override if custom_endpoint? && @api_path_override.present?
+
+      setting(:api_path, 'KI_TOOLBOX_API_PATH', DEFAULT_API_PATH)
+    end
+
+    def setting(key, env_key, default)
+      cfg[key].presence || ENV[env_key].presence || default
+    end
+
+    def cfg
+      @cfg ||= (Rails.configuration.labimotion_ai if Rails.configuration.respond_to?(:labimotion_ai)) || {}
+    end
+
+    def failure_message(statuses)
+      codes = statuses.map { |path, code| "#{path} → #{code || 'no response'}" }.join(', ')
+      # rubocop:disable Style/ArrayIntersect -- Array#intersect? is Ruby 3.1+;
+      # this gem still runs on 2.7.
+      if statuses.values.any? { |code| UNAUTHORIZED_CODES.include?(code) }
+        # rubocop:enable Style/ArrayIntersect
+        "#{base_url} rejected your API key (#{codes}). Create a new token in the provider UI and save it here."
+      elsif statuses.values.all?(&:nil?)
+        "#{base_url} did not respond#{network_error_suffix}."
+      else
+        "Could not read a model list from #{base_url} (tried #{codes}). " \
+          'The provider may not expose an OpenAI-compatible models endpoint.'
+      end
+    end
+
+    def network_error_suffix
+      @network_error.present? ? ": #{@network_error}" : ''
+    end
+  end
+end