Skip to content

Open-source live-chat, email support, omni-channel desk. An alternative to Intercom, Zendesk, Salesforce Service Cloud etc. 🔥💬

9.5 KB
Raw Blame
# == Schema Information
#
# Table name: captain_custom_tools
#
#  id                :bigint           not null, primary key
#  auth_config       :jsonb
#  auth_type         :string           default("none")
#  description       :text
#  enabled           :boolean          default(TRUE), not null
#  endpoint_url      :text             not null
#  headers           :jsonb            not null
#  http_method       :string           default("GET"), not null
#  param_schema      :jsonb
#  request_template  :text
#  response_template :text
#  settings          :jsonb            not null
#  slug              :string           not null
#  source_metadata   :jsonb
#  title             :string           not null
#  created_at        :datetime         not null
#  updated_at        :datetime         not null
#  account_id        :bigint           not null
#  assistant_id      :bigint
#
# Indexes
#
#  index_captain_custom_tools_on_account_id             (account_id)
#  index_captain_custom_tools_on_assistant_id_and_slug  (assistant_id,slug) UNIQUE
#
class Captain::CustomTool < ApplicationRecord
  class LimitExceededError < StandardError; end

  MAX_PER_ASSISTANT = 50

  include Concerns::Toolable
  include Concerns::SafeEndpointValidatable

  self.table_name = 'captain_custom_tools'

  NAME_PREFIX = 'custom'.freeze
  NAME_SEPARATOR = '_'.freeze
  # OpenAI enforces a 64-char limit on function names. The slug is used
  # verbatim as the tool name in LLM requests, so it must fit within this limit.
  MAX_SLUG_LENGTH = 64
  COLLISION_SUFFIX_LENGTH = 7 # "_" + 6 random alphanumeric chars
  # Header rules mirror the Captain tools catalog manifest schema
  MAX_HEADERS = 16
  MAX_HEADER_VALUE_BYTES = 1.kilobyte
  # RFC 9110 field-name token
  HEADER_NAME_PATTERN = /\A[!#$%&'*+.^_`|~0-9A-Za-z-]+\z/
  # Control characters, or install-time (${{ }}) and call-time ({{ }}) placeholders
  INVALID_HEADER_VALUE_PATTERN = /[[:cntrl:]]|\{\{/
  RESERVED_HEADERS = %w[authorization host content-length content-type].freeze
  # Any name starting with x-chatwoot, dash or not, is reserved for headers Chatwoot sets
  RESERVED_HEADER_PREFIX = 'x-chatwoot'.freeze
  # Values Chatwoot fills into a parameter from what the customer verified: an email by one-time code
  VERIFIED_SOURCES = %w[verified.email].freeze
  PARAM_SCHEMA_VALIDATION = {
    'type': 'array',
    'items': {
      'type': 'object',
      'properties': {
        'name': { 'type': 'string' },
        'type': { 'type': 'string' },
        'description': { 'type': 'string' },
        'required': { 'type': 'boolean' },
        'source': { 'enum': VERIFIED_SOURCES }
      },
      'required': %w[name type description],
      # Verified values are text, so a parameter that takes one must be a string
      'if': { 'required': ['source'] },
      'then': { 'properties': { 'type': { 'const': 'string' } } },
      'additionalProperties': false
    }
  }.to_json.freeze
  # Present only on tools installed from chatwoot/tools
  SOURCE_METADATA_VALIDATION = {
    'type': %w[object null],
    'properties': {
      'source': { 'const': 'github' },
      'repository': { 'type': 'string', 'pattern': '^[\\w.-]+/[\\w.-]+$' },
      'path': { 'type': 'string', 'pattern': '^[\\w.-]+$' },
      'tool_id': { 'type': 'string', 'pattern': '^[a-z][a-z0-9_]*$' },
      'revision': { 'type': 'string', 'pattern': '^[0-9a-f]{40}$' },
      'version': { 'type': 'string', 'minLength': 1 },
      'manifest_digest': { 'type': 'string', 'pattern': '^sha256:[0-9a-f]{64}$' },
      'installation_id': { 'type': 'string', 'format': 'uuid' }
    },
    'required': %w[source repository path tool_id revision version manifest_digest installation_id],
    'additionalProperties': false
  }.to_json.freeze

  # Only known settings with boolean values are accepted, so a typo or a string can never switch a safety setting off
  SETTING_KEYS = %w[requires_email_verification].freeze
  SETTINGS_VALIDATION = {
    'type': 'object',
    'properties': SETTING_KEYS.index_with { { 'type': 'boolean' } },
    'additionalProperties': false
  }.to_json.freeze

  belongs_to :account
  belongs_to :assistant, class_name: 'Captain::Assistant'

  enum :http_method, %w[GET POST PUT PATCH DELETE].index_by(&:itself), validate: true
  enum :auth_type, %w[none bearer basic api_key].index_by(&:itself), default: :none, validate: true, prefix: :auth

  encrypts :auth_config, :headers if Chatwoot.encryption_configured?

  before_validation :generate_slug
  before_create :ensure_within_limit

  validates :slug, presence: true, uniqueness: { scope: :assistant_id }, length: { maximum: MAX_SLUG_LENGTH }
  validates :title, presence: true
  validates :endpoint_url, presence: true
  validates_with JsonSchemaValidator,
                 schema: PARAM_SCHEMA_VALIDATION,
                 attribute_resolver: ->(record) { record.param_schema }
  validates_with JsonSchemaValidator,
                 schema: SOURCE_METADATA_VALIDATION,
                 attribute_resolver: ->(record) { record.source_metadata }
  validates_with JsonSchemaValidator,
                 schema: SETTINGS_VALIDATION,
                 attribute_resolver: ->(record) { record.settings }
  validate :validate_headers
  validate :validate_auth_config

  scope :enabled, -> { where(enabled: true) }
  scope :from_github, lambda { |repository, path|
    where("source_metadata->>'source' = 'github'")
      .where("source_metadata->>'repository' = ? AND source_metadata->>'path' = ?", repository, path)
  }

  def to_tool_metadata
    {
      id: slug,
      title: title,
      description: description,
      custom: true
    }
  end

  # The tool only runs for a customer who verified an email with a one-time code.
  # A tool with a parameter that takes the verified email cannot run without one, so it needs no setting.
  def requires_email_verification?
    settings['requires_email_verification'] == true || param_schema.any? { |param_def| param_def['source'] == 'verified.email' }
  end

  # The name of the parameter Chatwoot fills with the verified email, if the tool has one
  def verified_email_param
    param_schema.find { |param_def| param_def['source'] == 'verified.email' }&.dig('name')
  end

  def enabled_scenarios_count
    assistant.scenarios.enabled.where('tools @> ?', [slug].to_json).count
  end

  private

  def validate_headers
    return errors.add(:headers, I18n.t('captain.custom_tool.headers.invalid')) unless headers.is_a?(Hash)
    return errors.add(:headers, I18n.t('captain.custom_tool.headers.too_many', limit: MAX_HEADERS)) if headers.size > MAX_HEADERS

    names = headers.keys.map(&:downcase)
    errors.add(:headers, I18n.t('captain.custom_tool.headers.duplicate')) if names.uniq.size != names.size
    headers.each { |name, value| validate_header(name, value) }
  end

  # Auth values become request headers, and the HTTP client rejects unsafe ones on every call
  def validate_auth_config
    config = auth_config.to_h
    validate_api_key_name(config['name']) if auth_api_key? && config['name'].is_a?(String)
    errors.add(:auth_config, :invalid) if invalid_auth_value?(config)
  end

  # Basic auth is sent as username:password, so a colon in the username splits it in the wrong place
  def invalid_auth_value?(config)
    (auth_basic? && config['username'].to_s.include?(':')) ||
      config.values.any? { |value| value.is_a?(String) && value.match?(/[[:cntrl:]]/) }
  end

  # HttpTool sets reserved headers after auth, so they would overwrite the key. Authorization is the credential's own header.
  def validate_api_key_name(name)
    return errors.add(:auth_config, I18n.t('captain.custom_tool.headers.invalid_name', name: name)) unless HEADER_NAME_PATTERN.match?(name)
    return if name.casecmp?('authorization') || !reserved_header?(name.downcase)

    errors.add(:auth_config, I18n.t('captain.custom_tool.headers.reserved', name: name))
  end

  def validate_header(name, value)
    return errors.add(:headers, I18n.t('captain.custom_tool.headers.invalid_name', name: name)) unless HEADER_NAME_PATTERN.match?(name)
    return errors.add(:headers, I18n.t('captain.custom_tool.headers.reserved', name: name)) if reserved_header?(name.downcase)
    return if value.is_a?(String) && value.bytesize <= MAX_HEADER_VALUE_BYTES && !INVALID_HEADER_VALUE_PATTERN.match?(value)

    errors.add(:headers, I18n.t('captain.custom_tool.headers.invalid_value', name: name))
  end

  def reserved_header?(name)
    RESERVED_HEADERS.include?(name) || name.start_with?(RESERVED_HEADER_PREFIX)
  end

  def ensure_within_limit
    # Lock the assistant row to serialize concurrent creates and prevent exceeding the cap
    Captain::Assistant.lock.find(assistant_id)
    return if assistant.custom_tools.count < MAX_PER_ASSISTANT

    raise LimitExceededError, I18n.t('captain.custom_tool.limit_exceeded', limit: MAX_PER_ASSISTANT)
  end

  def generate_slug
    return if slug.present?
    return if title.blank?

    parameterized_title = title.parameterize(separator: NAME_SEPARATOR)
    base_slug = "#{NAME_PREFIX}#{NAME_SEPARATOR}#{parameterized_title}".truncate(MAX_SLUG_LENGTH, omission: '')
    self.slug = find_unique_slug(base_slug)
  end

  def find_unique_slug(base_slug)
    return base_slug unless slug_exists?(base_slug)

    truncated = base_slug.truncate(MAX_SLUG_LENGTH - COLLISION_SUFFIX_LENGTH, omission: '')
    5.times do
      slug_candidate = "#{truncated}#{NAME_SEPARATOR}#{SecureRandom.alphanumeric(6).downcase}"
      return slug_candidate unless slug_exists?(slug_candidate)
    end

    raise ActiveRecord::RecordNotUnique, I18n.t('captain.custom_tool.slug_generation_failed')
  end

  def slug_exists?(candidate)
    self.class.exists?(assistant_id: assistant_id, slug: candidate)
  end
end