connectors 0.1.0

data/lib/connectors/engine.rb

@@ -0,0 +1,123 @@
+ActiveSupport::Inflector.inflections(:en) do |inflect|
+  inflect.acronym "OAuth"
+end
+
+module Connectors
+  class Engine < ::Rails::Engine
+    isolate_namespace Connectors
+
+    config.generators.api_only = true
+
+    initializer :connectors_mcp_filter_secrets do |app|
+      app.config.filter_parameters += %i[bearer_token mcp_oauth client_information code state authorization_context arguments responses headers]
+    end
+
+    # Rails's built-in append_migrations sometimes misses path-based engine
+    # sources, so wire our migration directory in explicitly. Without this,
+    # `bin/rails db:migrate` in a host app silently skips the engine's
+    # tables.
+    initializer :connectors_append_engine_migrations do |app|
+      # Rails adds this engine's paths itself when running its Rake tasks.
+      # Adding them here too makes every migration appear twice.
+      next if defined?(ENGINE_ROOT) && File.expand_path(ENGINE_ROOT) == root.to_s
+
+      paths = app.config.paths["db/migrate"]
+      own   = ::Connectors::Engine.root.join("db/migrate").to_s
+      paths << own unless paths.to_a.include?(own)
+    end
+
+    # Register canonical base credential schemas so connectors can declare
+    # `extends :oauth2` (and inherit the OAuth2 form fields). The registry
+    # is process-local; reset between tests via the spec helper.
+    initializer :connectors_register_credential_types do
+      reg = ::Connectors::CredentialTypeRegistry
+      reg.register(:oauth2,           reg::OAUTH2)
+      # Phase 4 — n8n's `OAuth1Api` base type
+      # (packages/nodes-base/credentials/OAuth1Api.credentials.ts:1-72).
+      reg.register(:oauth1_api,       reg::OAUTH1)
+      # Phase 2 — n8n's generic HTTP auth credential types
+      # (packages/nodes-base/credentials/Http*Auth.credentials.ts).
+      reg.register(:http_basic_auth,  ::Connectors::CredentialTypes::HTTP_BASIC_AUTH)
+      reg.register(:http_bearer_auth, ::Connectors::CredentialTypes::HTTP_BEARER_AUTH)
+      reg.register(:http_header_auth, ::Connectors::CredentialTypes::HTTP_HEADER_AUTH)
+      reg.register(:http_query_auth,  ::Connectors::CredentialTypes::HTTP_QUERY_AUTH)
+      reg.register(:http_digest_auth, ::Connectors::CredentialTypes::HTTP_DIGEST_AUTH)
+      reg.register(:http_custom_auth, ::Connectors::CredentialTypes::HTTP_CUSTOM_AUTH)
+    end
+
+    # Connector classes register themselves with Connectors::Registry as a
+    # side effect of being loaded (the `connector key:, ...` DSL call in
+    # the class body). Zeitwerk autoloads on-demand though — so without
+    # something pulling each class in, `GET /connectors/types` would return
+    # an empty list in dev. Force-load every `app/connectors/<key>/connector.rb`
+    # on boot so the registry is populated before the first request.
+    #
+    # Walks every Engine root (including the host's main app) and globs each
+    # one's `app/connectors/` — the union covers shipped connectors here in
+    # the engine, plus host-app overrides under flow-api's own
+    # `app/connectors/` (if/when the host decides to ship its own).
+    config.to_prepare do
+      ::Rails::Engine.subclasses.map(&:instance).push(::Rails.application).uniq.each do |engine|
+        dir = engine.root.join("app/connectors")
+        next unless dir.directory?
+        dir.glob("*/connector.rb").each { |f| require_dependency f.to_s }
+      end
+    end
+
+    # Returns the path the engine is actually mounted at in the host app —
+    # `/connectors`, `/api/v1/connectors`, anything the host chose. Walks
+    # the host's compiled route table to find this engine's mount; falls
+    # back to `/connectors` only when the engine isn't mounted (isolated
+    # specs that boot without a full app). Cached after first lookup; the
+    # `to_prepare` block above ensures it's still warm after code reloads.
+    #
+    # Used by every URL builder in the engine that needs to round-trip an
+    # absolute URL back to the engine's own routes (OAuth callback,
+    # default webhook URL, types-endpoint `redirect_uri` field) so that
+    # `mount Engine => "/api/v1/connectors"` Just Works without any host
+    # configuration beyond the routes line itself.
+    def self.mount_path
+      return @mount_path if defined?(@mount_path) && @mount_path
+      @mount_path = lookup_mount_path
+    end
+
+    # Reset the cache. Call after re-mounting in a spec; the host never
+    # needs this in normal operation.
+    def self.reset_mount_path!
+      remove_instance_variable(:@mount_path) if defined?(@mount_path)
+    end
+
+    def self.lookup_mount_path
+      return "/connectors" unless defined?(::Rails) && ::Rails.application&.routes
+      ::Rails.application.routes.routes.each do |route|
+        next unless route_targets_engine?(route)
+        path = route.path.spec.to_s.dup
+        path.chomp!("(.:format)")
+        path.chomp!("/")
+        return path.empty? ? "/" : path
+      end
+      "/connectors"
+    end
+
+    # Mounted engines sit at varying depths in `route.app`'s wrapper chain.
+    # In a bare host (`mount Connectors::Engine => "/connectors"`) the
+    # chain is `Constraints → Connectors::Engine`. Inside a namespace
+    # (`namespace :api { scope "v1" { mount Connectors::Engine => "/connectors" } }`)
+    # the chain becomes `Constraints → Connectors::Engine → LazyRouteSet`,
+    # so unwrapping to the terminal misses the engine entirely. Walk every
+    # layer instead and stop the first time we encounter `self`.
+    def self.route_targets_engine?(route)
+      target  = route.app
+      visited = {}
+      while target && !visited[target.object_id]
+        return true if target == self
+        visited[target.object_id] = true
+        return false unless target.respond_to?(:app)
+        nxt = target.app
+        return false if nxt == target
+        target = nxt
+      end
+      false
+    end
+  end
+end

data/lib/connectors/errors.rb

@@ -0,0 +1,88 @@
+module Connectors
+  class Error < StandardError; end
+
+  class UnknownConnector < Error
+    def initialize(key, known: [])
+      super("no connector registered for #{key.inspect}. Known keys: #{known.inspect}")
+    end
+  end
+
+  class UnknownAuthScheme < Error
+    def initialize(name, known: [])
+      super("no auth scheme registered for #{name.inspect}. Known schemes: #{known.inspect}")
+    end
+  end
+
+  class MissingCredentialFields < Error
+    def initialize(fields)
+      super("missing required credential fields: #{Array(fields).join(', ')}")
+    end
+  end
+
+  class ApiError < Error
+    attr_reader :status, :body
+
+    def initialize(message, status: nil, body: nil)
+      super(message)
+      @status = status
+      @body   = body
+    end
+  end
+
+  class AuthenticationFailed < ApiError; end
+  class Forbidden < ApiError; end
+
+  # A credential was used with a node that's not on its `supported_nodes`
+  # allowlist, OR the credential is marked generic_auth-only and the caller
+  # is a non-HTTP-Request node. Mirrors the visibility gate n8n applies via
+  # the credential's `supportedNodes` field (interfaces.ts:381) and
+  # `genericAuth` flag (interfaces.ts:379).
+  class CredentialNotPermitted < Error
+    def initialize(connector_key, node_type, reason: nil)
+      msg = "credential #{connector_key.inspect} is not permitted for node #{node_type.inspect}"
+      msg += " (#{reason})" if reason
+      super(msg)
+    end
+  end
+
+  class RateLimited < ApiError
+    attr_reader :retry_after
+
+    def initialize(message, status: nil, body: nil, retry_after: nil)
+      super(message, status: status, body: body)
+      @retry_after = retry_after
+    end
+  end
+
+  # Caller tried to invoke an action that wasn't declared on the connector.
+  # Mirrors UnknownConnector: includes the known set so the frontend can
+  # render a helpful error.
+  class UnknownAction < Error
+    attr_reader :action_key, :connector_key, :known
+
+    def initialize(action_key, connector_key: nil, known: [])
+      @action_key    = action_key
+      @connector_key = connector_key
+      @known         = known
+      msg = "no action #{action_key.inspect} declared"
+      msg += " on connector #{connector_key.inspect}" if connector_key
+      msg += ". Known actions: #{known.inspect}" if known.any?
+      super(msg)
+    end
+  end
+
+  # Action params failed schema validation — missing required fields or
+  # extraneous unknown fields. Surfaced as a 422 from the actions endpoint.
+  class InvalidActionParams < Error
+    attr_reader :missing, :unknown
+
+    def initialize(missing: [], unknown: [])
+      @missing = Array(missing)
+      @unknown = Array(unknown)
+      parts = []
+      parts << "missing required params: #{@missing.join(', ')}" if @missing.any?
+      parts << "unknown params: #{@unknown.join(', ')}"          if @unknown.any?
+      super(parts.join("; ").presence || "invalid action params")
+    end
+  end
+end

data/lib/connectors/grant_policy.rb

@@ -0,0 +1,13 @@
+module Connectors
+  # Shared by HTTP endpoints and services invoked by workers.
+  class GrantPolicy
+    ROLE_RANK = { "viewer" => 0, "editor" => 1, "owner" => 2 }.freeze
+
+    def self.role_for(grant, owner:, principals:)
+      return unless owner
+      return "owner" if grant.owner_type == owner.class.polymorphic_name && grant.owner_id == owner.id
+      roles = grant.shares.for_principals(principals).pluck(:role)
+      roles.max_by { |role| ROLE_RANK.fetch(role) }
+    end
+  end
+end

data/lib/connectors/mcp/access.rb

@@ -0,0 +1,50 @@
+module Connectors
+  module MCP
+    class Access
+      RANK = GrantPolicy::ROLE_RANK
+      attr_reader :grant, :actor, :principals
+
+      def initialize(grant:, actor:, principals: nil)
+        @grant, @actor = grant, actor
+        @principals = principals || (actor ? [ [ actor.class.polymorphic_name, actor.id ] ] : [])
+      end
+
+      def require!(role = :viewer)
+        grant.reload
+        raise AccessDenied, "MCP grant is unavailable" unless Registry.fetch(grant.connector_key).mcp? && !grant.revoked?
+        actual = role_for
+        raise AccessDenied, "MCP grant requires #{role} access" unless actual && RANK.fetch(actual) >= RANK.fetch(role.to_s)
+        self
+      rescue ActiveRecord::RecordNotFound, Connectors::UnknownConnector
+        raise AccessDenied, "MCP grant is unavailable"
+      end
+
+      def role_for
+        GrantPolicy.role_for(grant, owner: actor, principals: principals)
+      end
+
+      def fingerprint
+        data = canonical(configuration.except("mcp_oauth"))
+        Digest::SHA256.hexdigest(JSON.generate([ grant.owner_type, grant.owner_id, grant.is_managed, grant.external_ref, data ]))
+      end
+
+      def configuration
+        ConnectionConfig.resolve(grant.credentials_hash, connector: Registry.fetch(grant.connector_key), internal: true)
+      end
+
+      def actor_key
+        actor.to_global_id.to_s
+      end
+
+      private
+
+      def canonical(value)
+        case value
+        when Hash then value.sort_by { |key, _| key.to_s }.to_h.transform_values { |item| canonical(item) }
+        when Array then value.map { |item| canonical(item) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/connectors/mcp/authorization.rb

@@ -0,0 +1,177 @@
+module Connectors
+  module MCP
+    class Authorization
+      def initialize(grant:, actor:, principals: nil)
+        @access = Access.new(grant: grant, actor: actor, principals: principals)
+      end
+
+      def start(challenge: {})
+        @access.require!(:owner)
+        data = @access.configuration
+        raise ConfigurationRequired, "Connection does not use OAuth" unless data["auth_mode"] == "oauth"
+        fingerprint = @access.fingerprint
+        resource, metadata = AuthorizationDiscovery.new(server_url: data.fetch("server_url"), issuer: data["authorization_server"]).call(challenge)
+        unless Array(metadata["code_challenge_methods_supported"]).include?("S256")
+          raise ConfigurationRequired, "Authorization server must advertise PKCE S256"
+        end
+        callback = callback_url
+        HTTP.new.validate_url!(callback)
+        scopes = requested_scopes(data, resource, metadata, challenge)
+        client = register_client(data, metadata, callback)
+        pkce = ::MCP::Client::OAuth::PKCE.generate
+        state = SecureRandom.urlsafe_base64(32)
+        @access.require!(:owner)
+        raise AccessDenied, "MCP configuration changed" unless fingerprint == @access.fingerprint
+        payload = { "metadata" => metadata, "client" => client, "resource" => ::MCP::Client::OAuth::Discovery.canonicalize_url(data.fetch("server_url")),
+          "callback" => callback, "code_verifier" => pkce.fetch(:code_verifier), "requested_scopes" => scopes }
+        Connectors::McpAuthorization.create!(grant: @access.grant, actor_key: @access.actor_key, fingerprint: fingerprint,
+          state_digest: Digest::SHA256.hexdigest(state), expires_at: Connectors.configuration.mcp.transaction_ttl.from_now, payload: payload)
+        uri = URI(metadata.fetch("authorization_endpoint"))
+        query = URI.decode_www_form(uri.query.to_s).to_h.merge("response_type" => "code", "client_id" => client.fetch("client_id"),
+          "redirect_uri" => callback, "state" => state, "code_challenge" => pkce.fetch(:code_challenge), "code_challenge_method" => "S256", "resource" => payload.fetch("resource"))
+        query["scope"] = scopes.join(" ") if scopes.any?
+        uri.query = URI.encode_www_form(query)
+        uri.to_s
+      end
+
+      def complete(state:, code: nil, iss: nil, error: nil)
+        @access.require!(:owner)
+        record = Connectors::McpAuthorization.find_by(state_digest: Digest::SHA256.hexdigest(state.to_s))
+        raise AccessDenied, "Invalid MCP authorization state" unless record
+        payload = record.claim!(@access)
+        claimed = true
+        metadata = payload.fetch("metadata")
+        if (iss && iss != metadata["issuer"]) || (iss.nil? && metadata["authorization_response_iss_parameter_supported"] == true)
+          raise AccessDenied, "Authorization response issuer mismatch"
+        end
+        raise AccessDenied, "Authorization was denied or incomplete" if error || code.to_s.empty?
+        locked do
+          @access.require!(:owner)
+          raise AccessDenied, "MCP configuration changed" unless record.fingerprint == @access.fingerprint
+          tokens = TokenEndpoint.exchange(metadata: metadata, client: resolve_client(payload.fetch("client")), params: {
+            "grant_type" => "authorization_code", "code" => code, "redirect_uri" => payload.fetch("callback"),
+            "code_verifier" => payload.fetch("code_verifier"), "resource" => payload.fetch("resource") })
+          persist(payload, tokens)
+        end
+        record.update!(status: "complete", payload: { "cleared" => true })
+        true
+      ensure
+        record.update!(status: "failed", payload: { "cleared" => true }) if claimed && record.status == "claimed"
+      end
+
+      def access_token
+        @access.require!
+        stored = @access.grant.credentials_hash["mcp_oauth"]
+        raise AuthorizationRequired unless stored && stored["fingerprint"] == @access.fingerprint
+        tokens = stored.fetch("tokens")
+        return tokens.fetch("access_token") unless tokens["expires_at"] && tokens["expires_at"] <= Time.current.to_f + 30
+        refresh(expected_token: tokens["access_token"])
+      end
+
+      def refresh(expected_token:)
+        invalid = false
+        token = locked do
+          @access.require!
+          stored = @access.grant.credentials_hash["mcp_oauth"]
+          raise AuthorizationRequired unless stored && stored["fingerprint"] == @access.fingerprint
+          previous = stored.fetch("tokens")
+          return previous.fetch("access_token") unless previous["access_token"] == expected_token
+          raise AuthorizationRequired if previous["refresh_token"].blank?
+          begin
+            tokens = TokenEndpoint.exchange(metadata: stored.fetch("metadata"), client: resolve_client(stored.fetch("client")), params: {
+              "grant_type" => "refresh_token", "refresh_token" => previous.fetch("refresh_token"), "resource" => stored.fetch("resource") })
+          rescue HTTPError => error
+            raise unless error.status == 400 && invalid_grant?(error.body)
+            # Clear under the same lock, and commit before reporting reconnect.
+            @access.grant.update_credentials!("mcp_oauth" => nil)
+            invalid = true
+            next
+          end
+          tokens["refresh_token"] = previous["refresh_token"] unless tokens.key?("refresh_token")
+          persist(stored, tokens)
+          tokens.fetch("access_token")
+        end
+        raise AuthorizationRequired if invalid
+        token
+      end
+
+      private
+
+      def locked(&block)
+        Timeout.timeout(Connectors.configuration.mcp.request_timeout, TransportError, "MCP authorization deadline exceeded") do
+          @access.grant.with_lock(&block)
+        end
+      end
+
+      def resolve_client(client)
+        return client unless client["configured"]
+        configured = @access.grant.credentials_hash["client_information"]
+        unless configured && configured["client_id"] == client["client_id"] && configured["issuer"] == client["issuer"]
+          raise ConfigurationRequired, "Configured OAuth client changed"
+        end
+        configured
+      end
+
+      def invalid_grant?(body)
+        JSON.parse(body)["error"] == "invalid_grant"
+      rescue JSON::ParserError, TypeError
+        false
+      end
+
+      def persist(payload, tokens)
+        value = payload.slice("metadata", "client", "resource", "requested_scopes").merge("tokens" => tokens, "fingerprint" => @access.fingerprint)
+        @access.grant.update_credentials!("mcp_oauth" => value)
+        @access.grant.update!(expires_at: tokens["expires_at"] && Time.at(tokens["expires_at"]), status: :active)
+      end
+
+      def callback_url
+        Connectors.configuration.resolved_mcp_callback_url
+      end
+
+      def requested_scopes(data, resource, metadata, challenge)
+        scopes = if challenge.key?("scope")
+          challenge.fetch("scope").to_s.split
+        else
+          Array(resource["scopes_supported"])
+        end
+        scopes |= Array(data.dig("mcp_oauth", "requested_scopes"))
+        if Array(metadata["scopes_supported"]).include?("offline_access")
+          scopes |= [ "offline_access" ]
+        else
+          scopes -= [ "offline_access" ]
+        end
+        raise ProtocolError, "Invalid OAuth scopes" unless scopes.all? { |s| s.is_a?(String) && s.match?(/\A[\x21\x23-\x5B\x5D-\x7E]+\z/) }
+        scopes
+      end
+
+      def register_client(data, metadata, callback)
+        client = data["client_information"] || data.dig("mcp_oauth", "client")
+        if client
+          raise ConfigurationRequired, "OAuth client issuer mismatch" unless client["issuer"] == metadata["issuer"]
+          return client.slice("client_id", "issuer", "token_endpoint_auth_method").merge("configured" => true) if data["client_information"]
+          return client
+        end
+        document_url = Connectors.configuration.mcp.client_metadata_url
+        if document_url && metadata["client_id_metadata_document_supported"] == true
+          uri = HTTP.new.validate_url!(document_url)
+          raise ConfigurationRequired, "CIMD requires an HTTPS document path" unless uri.scheme == "https" && uri.path.present? && uri.path != "/" && !uri.query
+          document = HTTP.new.json(url: document_url)
+          unless document["client_id"] == document_url && document["client_name"].is_a?(String) && Array(document["redirect_uris"]).include?(callback)
+            raise ConfigurationRequired, "Invalid client metadata document"
+          end
+          return document.slice("client_id", "token_endpoint_auth_method").merge("issuer" => metadata.fetch("issuer"))
+        end
+        endpoint = metadata["registration_endpoint"] or raise ConfigurationRequired, "Pre-registered client information is required"
+        grant_types = [ "authorization_code", "refresh_token" ]
+        grant_types &= Array(metadata["grant_types_supported"]) if metadata.key?("grant_types_supported")
+        raise ConfigurationRequired, "Authorization server does not support authorization_code" unless grant_types.include?("authorization_code")
+        client = HTTP.new.json(url: endpoint, method: :post, headers: { "Content-Type" => "application/json" }, body: {
+          client_name: Connectors.configuration.mcp.client_name, redirect_uris: [ callback ], grant_types: grant_types,
+          response_types: [ "code" ], token_endpoint_auth_method: "none", application_type: "web"
+        }.to_json)
+        raise ProtocolError, "Registration returned no client ID" unless client["client_id"].is_a?(String) && client["client_id"].present?
+        client.merge("issuer" => metadata.fetch("issuer"))
+      end
+    end
+  end
+end

data/lib/connectors/mcp/authorization_context.rb

@@ -0,0 +1,25 @@
+module Connectors
+  module MCP
+    # Carries a server-issued challenge from a failed call to the owner's consent screen.
+    # The browser cannot replace discovery URLs or scopes inside it.
+    module AuthorizationContext
+      module_function
+
+      def encode(grant:, challenge:, fingerprint: nil)
+        access = Access.new(grant: grant, actor: grant.owner)
+        OAuth::State.encode(connector_key: "mcp", owner_gid: grant.owner.to_global_id.to_s,
+          extra: { "purpose" => "mcp_challenge", "grant_id" => grant.id, "fingerprint" => fingerprint || access.fingerprint, "challenge" => challenge })
+      end
+
+      def decode(token, access:)
+        access.require!(:owner)
+        state = OAuth::State.decode(token)
+        extra = state&.dig("x")
+        unless state && state["k"] == "mcp" && state["o"] == access.actor_key && extra.is_a?(Hash) && extra["purpose"] == "mcp_challenge" && extra["grant_id"] == access.grant.id && extra["fingerprint"] == access.fingerprint
+          raise AccessDenied, "Invalid MCP authorization context"
+        end
+        extra.fetch("challenge")
+      end
+    end
+  end
+end

data/lib/connectors/mcp/authorization_discovery.rb

@@ -0,0 +1,42 @@
+module Connectors
+  module MCP
+    class AuthorizationDiscovery
+      SDK = ::MCP::Client::OAuth::Discovery
+
+      def initialize(server_url:, issuer: nil)
+        @server_url, @issuer = server_url, issuer
+        @http = HTTP.new
+      end
+
+      def call(challenge = {})
+        @http.validate_url!(@server_url)
+        resource = fetch_first(SDK.protected_resource_metadata_urls(server_url: @server_url, resource_metadata_url: challenge["resource_metadata"]))
+        unless resource["resource"].is_a?(String) && SDK.resource_covers?(prm: resource["resource"], server: @server_url)
+          raise ConfigurationRequired, "Protected resource metadata does not cover this MCP server"
+        end
+        issuers = resource["authorization_servers"]
+        raise ConfigurationRequired, "No authorization server advertised" unless issuers.is_a?(Array) && issuers.any? && issuers.all? { |v| v.is_a?(String) }
+        issuer = @issuer || issuers.first
+        raise ConfigurationRequired, "Configured issuer is not advertised" unless issuers.include?(issuer)
+        @http.validate_url!(issuer)
+        metadata = fetch_first(SDK.authorization_server_metadata_urls(issuer))
+        raise ConfigurationRequired, "Authorization issuer mismatch" unless metadata["issuer"] == issuer
+        %w[authorization_endpoint token_endpoint].each { |key| @http.validate_url!(metadata.fetch(key, "")) }
+        [ resource, metadata ]
+      end
+
+      private
+
+      def fetch_first(urls)
+        urls.each do |url|
+          begin
+            return @http.json(url: url, headers: { "Accept" => "application/json" })
+          rescue HTTPError => error
+            raise unless [ 404, 405 ].include?(error.status)
+          end
+        end
+        raise ConfigurationRequired, "MCP authorization metadata unavailable"
+      end
+    end
+  end
+end

data/lib/connectors/mcp/cancellation.rb

@@ -0,0 +1,36 @@
+module Connectors
+  module MCP
+    class Cancellation
+      def initialize
+        @mutex = Mutex.new
+        @cancelled = false
+        @callbacks = {}
+      end
+
+      def cancel
+        callbacks = @mutex.synchronize do
+          @cancelled = true
+          @callbacks.values.dup
+        end
+        callbacks.each(&:call)
+      end
+
+      def check!
+        raise Cancelled, "MCP request cancelled" if @mutex.synchronize { @cancelled }
+      end
+
+      def attach(&abort)
+        @mutex.synchronize do
+          raise Cancelled, "MCP request cancelled" if @cancelled
+          key = Object.new
+          @callbacks[key] = abort
+          key
+        end
+      end
+
+      def detach(key)
+        @mutex.synchronize { @callbacks.delete(key) }
+      end
+    end
+  end
+end