connectors 0.1.0

data/lib/connectors/middleware/auto_refresh.rb

@@ -0,0 +1,71 @@
+require "faraday"
+
+module Connectors
+  module Middleware
+    # Catches AuthenticationFailed (raised by ErrorNormalization on 401), asks
+    # the connector to refresh its credentials, then retries the request once.
+    # Bails out if:
+    #   - the connector hasn't overridden #refresh!
+    #   - the request was already retried in this call chain
+    #   - the refresh itself fails (re-raises the underlying error)
+    class AutoRefresh < Faraday::Middleware
+      def initialize(app, grant:)
+        super(app)
+        @grant = grant
+      end
+
+      def call(env)
+        credentials = @grant.credentials_hash.deep_dup
+        request_body = env.body
+        @app.call(env)
+      rescue Connectors::AuthenticationFailed => e
+        raise e if env[:connectors_already_refreshed]
+        raise e unless refreshable?
+
+        perform_refresh!(credentials)
+        env[:connectors_already_refreshed] = true
+        env[:request_headers].delete("Authorization")
+        env.body = request_body
+        @app.call(env)
+      end
+
+      private
+
+      # True only when the connector subclass actually implements refresh!.
+      # The base Connector#refresh! raises NotImplementedError, which we don't
+      # want to trigger accidentally.
+      def refreshable?
+        klass = @grant.connector.class
+        klass.instance_method(:refresh!).owner != Connectors::Connector
+      end
+
+      def perform_refresh!(failed_credentials)
+        failure = nil
+        @grant.with_persistence_lock do
+          raise Connectors::AuthenticationFailed, "connection has been revoked" if @grant.revoked?
+          # Another worker may have refreshed while this request was in flight.
+          next unless @grant.credentials_hash == failed_credentials
+
+          begin
+            @grant.connector.refresh!
+            @grant.reload if @grant.persisted?
+          rescue Connectors::Error => e
+            mark_errored!
+            failure = e
+          rescue StandardError => e
+            mark_errored!
+            failure = Connectors::AuthenticationFailed.new("token refresh failed: #{e.class}")
+          end
+        end
+        # Raise after committing failure bookkeeping, not inside the transaction.
+        raise failure if failure
+      end
+
+      def mark_errored!
+        @grant.update_columns(status: Connectors::Grant.statuses[:errored])
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/connectors/middleware/error_normalization.rb

@@ -0,0 +1,45 @@
+require "faraday"
+
+module Connectors
+  module Middleware
+    # Converts non-2xx HTTP responses into typed Connectors::* exceptions so
+    # callers can rescue with intent rather than parsing status codes.
+    class ErrorNormalization < Faraday::Middleware
+      def initialize(app, token_expired_status: 401)
+        super(app)
+        @token_expired_status = token_expired_status
+      end
+
+      def on_complete(env)
+        return if env.status.between?(200, 299)
+
+        if env.status == @token_expired_status
+          raise Connectors::AuthenticationFailed.new(
+            "authentication failed (status #{env.status})",
+            status: env.status,
+            body: env.body
+          )
+        end
+
+        case env.status
+        when 403
+          raise Connectors::Forbidden.new("request forbidden (status 403)", status: env.status, body: env.body)
+        when 429
+          retry_after = env.response_headers["retry-after"] || env.response_headers["Retry-After"]
+          raise Connectors::RateLimited.new(
+            "remote rate limit (status 429)",
+            status:      429,
+            body:        env.body,
+            retry_after: retry_after&.to_i
+          )
+        else
+          raise Connectors::ApiError.new(
+            "API request failed (status #{env.status})",
+            status: env.status,
+            body: env.body
+          )
+        end
+      end
+    end
+  end
+end

data/lib/connectors/middleware/grant_status.rb

@@ -0,0 +1,19 @@
+require "faraday"
+
+module Connectors
+  module Middleware
+    # Runs inside the retry middleware so every attempt checks revocation
+    # before pre-authentication or provider credentials can be used.
+    class GrantStatus < Faraday::Middleware
+      def initialize(app, grant:)
+        super(app)
+        @grant = grant
+      end
+
+      def call(env)
+        @grant.ensure_not_revoked!
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/connectors/middleware/pre_authentication.rb

@@ -0,0 +1,54 @@
+module Connectors
+  module Middleware
+    # Runs the connector's `pre_authentication` block (Phase 3) before each
+    # outgoing request — but only when the cached credentials look stale.
+    # Mirrors n8n's contract at packages/workflow/src/interfaces.ts:374-377;
+    # n8n's runtime gates re-runs on `credentialsExpired: boolean` (see
+    # `ICredentialsHelper.runPreAuthentication` at :232-238). We use the
+    # same conceptual signal: if the credentials hash carries an
+    # `expires_at` (unix seconds) and it's in the past — OR no expires_at
+    # has ever been set — the hook fires and its return value is merged
+    # into the grant's credentials before the AuthenticateGeneric step.
+    #
+    # Reference impl: CrowdStrikeOAuth2Api.credentials.ts:62-76 — fetches
+    # an access token from `/oauth2/token` using client_id + client_secret,
+    # returns `{ sessionToken }` which feeds `authenticate.headers.Authorization`.
+    class PreAuthentication < Faraday::Middleware
+      def initialize(app, grant:, pre_auth_block:)
+        super(app)
+        @grant   = grant
+        @block   = pre_auth_block
+        @helpers = PreAuthenticationHelpers.new
+      end
+
+      def call(env)
+        refresh_if_expired!
+        @app.call(env)
+      end
+
+      private
+
+      def refresh_if_expired!
+        return unless credentials_expired?
+        @grant.with_persistence_lock do
+          next unless credentials_expired?
+          delta = run_block
+          next if delta.nil? || delta.empty?
+          @grant.update_credentials!(delta.transform_keys(&:to_s))
+        end
+      end
+
+      def credentials_expired?
+        expires_at = @grant.credentials_hash["expires_at"]
+        return true if expires_at.nil?
+        Time.now.to_i >= expires_at.to_i
+      end
+
+      def run_block
+        @block.call(@grant.credentials_hash, @helpers)
+      rescue => e
+        raise Connectors::AuthenticationFailed.new("pre_authentication failed: #{e.class}: #{e.message}")
+      end
+    end
+  end
+end

data/lib/connectors/middleware/rate_limit.rb

@@ -0,0 +1,40 @@
+require "faraday"
+
+module Connectors
+  module Middleware
+    # Per-grant token-bucket rate limiter backed by Rails.cache (typically Solid
+    # Cache in production). No-op unless the connector class declares
+    # `rate_limit count, per: window`.
+    #
+    #   class SlackConnector < Connectors::Connector
+    #     connector  key: :slack, auth: :oauth2, base_url: "..."
+    #     rate_limit 50, per: 1.minute
+    #   end
+    class RateLimit < Faraday::Middleware
+      def initialize(app, grant:)
+        super(app)
+        @grant = grant
+      end
+
+      def call(env)
+        config = @grant.connector.class.rate_limit_config
+        enforce!(config) if config
+        @app.call(env)
+      end
+
+      private
+
+      def enforce!(config)
+        key   = "connectors:ratelimit:#{@grant.connector_key}:#{@grant.id}"
+        count = Rails.cache.increment(key, 1, expires_in: config[:per])
+        count ||= Rails.cache.write(key, 1, expires_in: config[:per]) && 1
+
+        return if count <= config[:limit]
+        raise Connectors::RateLimited.new(
+          "local rate limit exceeded (#{config[:limit]} per #{config[:per].inspect})",
+          status: 429
+        )
+      end
+    end
+  end
+end

data/lib/connectors/oauth/authorize_url.rb

@@ -0,0 +1,78 @@
+require "uri"
+
+module Connectors
+  module OAuth
+    # Builds the URL we redirect the owner to so they can authorize the
+    # connector. Includes an encrypted `state` token that the callback validates.
+    class AuthorizeUrl
+      def self.for(connector_class, owner:, return_to: nil, scope: nil, name: nil, grant: nil)
+        new(connector_class).build(owner: owner, return_to: return_to, scope: scope, name: name, grant: grant)
+      end
+
+      def initialize(connector_class)
+        @connector_class = connector_class
+        @config          = connector_class.oauth2_config or
+          raise Connectors::Error.new("#{connector_class}: oauth2 ... DSL not declared")
+        @secrets         = Connectors.configuration.oauth_credentials_for(connector_class.connector_key)
+      end
+
+      # The connector declares a DEFAULT scope set; callers can override it
+      # per request via the `scope:` argument (multi-tenant hosts often
+      # need a wider or narrower scope than the connector's baseline).
+      # n8n's `Gmail OAuth2 API.credentials.ts` does the same thing — the
+      # node ships defaults, the workflow editor can ask for more.
+      def build(owner:, return_to: nil, scope: nil, name: nil, grant: nil)
+        pkce = pkce_params if @config[:grant_type].to_s == "pkce"
+
+        extras = {}
+        extras["cv"] = pkce[:verifier] if pkce
+        extras["n"]  = name            if name.to_s.length.positive?
+        if grant
+          extras["g"] = grant.id
+          extras["v"] = GrantWriter.fingerprint(grant)
+        end
+
+        state = State.encode(
+          connector_key: @connector_class.connector_key,
+          owner_gid:     owner.to_global_id.to_s,
+          return_to:     return_to,
+          extra:         extras.empty? ? nil : extras
+        )
+
+        effective_scope = scope.presence || @config[:scope]
+
+        params = {
+          response_type: "code",
+          client_id:     @secrets[:client_id],
+          redirect_uri:  redirect_uri,
+          scope:         effective_scope,
+          state:         state
+        }
+        if pkce
+          params[:code_challenge]        = pkce[:challenge]
+          params[:code_challenge_method] = pkce[:method]
+        end
+        params = params.merge(@config[:extra_authorize_params] || {}).compact
+
+        uri = URI.parse(@config[:authorize_url])
+        existing = URI.decode_www_form(uri.query.to_s)
+        uri.query = URI.encode_www_form(existing + params.to_a)
+        uri.to_s
+      end
+
+      private
+
+      def pkce_params
+        Connectors::OAuth::Pkce.generate
+      end
+
+      # Reads from Connectors.configuration.app_callback_url when the host
+      # has wired a separate frontend callback page (Activepieces-style split
+      # frontend/backend); otherwise falls back to the engine's own
+      # `/<connector>/callback` route (n8n-style monolithic).
+      def redirect_uri
+        Connectors.configuration.resolved_app_callback_url(@connector_class.connector_key)
+      end
+    end
+  end
+end

data/lib/connectors/oauth/client_authentication.rb

@@ -0,0 +1,24 @@
+require "base64"
+require "uri"
+
+module Connectors
+  module OAuth
+    # RFC 6749 client authentication, shared by code, refresh and client-
+    # credentials grants. A public PKCE client sends only its client ID.
+    module ClientAuthentication
+      module_function
+
+      def apply(body, headers, secrets:, authentication:)
+        if secrets[:client_secret].blank? || authentication == "body"
+          body[:client_id] = secrets[:client_id]
+          body[:client_secret] = secrets[:client_secret] if secrets[:client_secret].present?
+        elsif authentication == "header"
+          encoded = [ secrets[:client_id], secrets[:client_secret] ].map { |value| URI.encode_www_form_component(value.to_s) }
+          headers["Authorization"] = "Basic #{Base64.strict_encode64(encoded.join(':'))}"
+        else
+          raise ArgumentError, "unsupported OAuth client authentication: #{authentication.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/connectors/oauth/client_credentials.rb

@@ -0,0 +1,43 @@
+require "faraday"
+require "uri"
+
+module Connectors
+  module OAuth
+    # Server-to-server OAuth2 flow — no user redirect. POSTs
+    # `grant_type=client_credentials` + `client_id`/`client_secret` to the
+    # provider's token endpoint and returns a normalized token hash that the
+    # OAuthController writes to a new or explicitly selected Grant.
+    #
+    # n8n parity: `OAuth2Api.credentials.ts:1-45` declares the `grantType`
+    # field with `clientCredentials` as one option; the runtime branch lives
+    # at `oauth.service.ts:783-789`.
+    class ClientCredentials
+      def self.exchange(connector_class)
+        new(connector_class).exchange
+      end
+
+      def initialize(connector_class)
+        @connector_class = connector_class
+        @config          = connector_class.oauth2_config or
+          raise Connectors::Error.new("#{connector_class}: oauth2 ... DSL not declared")
+        @secrets         = Connectors.configuration.oauth_credentials_for(connector_class.connector_key)
+      end
+
+      def exchange
+        body = { grant_type: "client_credentials" }
+        body[:scope] = @config[:scope] if @config[:scope].to_s.length.positive?
+
+        headers = { "Content-Type" => "application/x-www-form-urlencoded", "Accept" => "application/json" }
+
+        ClientAuthentication.apply(body, headers, secrets: @secrets, authentication: @config[:authentication])
+
+        response = Faraday.post(@config[:token_url], URI.encode_www_form(body), headers) do |request|
+          request.options.open_timeout = ClientBuilder::DEFAULT_OPEN_TIMEOUT
+          request.options.timeout = ClientBuilder::DEFAULT_TIMEOUT
+        end
+        parsed = TokenResponse.parse(response)
+        @connector_class.post_token_exchange(parsed, TokenResponse.normalize(parsed))
+      end
+    end
+  end
+end

data/lib/connectors/oauth/grant_writer.rb

@@ -0,0 +1,73 @@
+require "digest"
+
+module Connectors
+  module OAuth
+    # New authorizations create new connections. Reconnection must name an
+    # existing connection and preserve its owner, provider and known account.
+    class GrantWriter
+      def self.fingerprint(grant)
+        Digest::SHA256.hexdigest(JSON.generate([ grant.credentials, grant.external_account_id, grant.status ]))
+      end
+
+      def initialize(owner:, connector_class:, grant_id: nil, fingerprint: nil)
+        @owner = owner
+        @connector_class = connector_class
+        @grant_id = grant_id
+        @fingerprint = fingerprint
+      end
+
+      def validate!
+        return unless @grant_id
+        verify_snapshot!(target)
+      end
+
+      def call(tokens, name: nil)
+        unless @grant_id
+          grant = Grant.new(owner: @owner, connector_key: @connector_class.connector_key.to_s)
+          return persist(grant, tokens, name)
+        end
+
+        grant = target
+        grant.with_lock do
+          # Ownership/credentials may have changed while the provider request
+          # was in flight. Never overwrite that newer connection snapshot.
+          verify_snapshot!(grant)
+          persist(grant, tokens, name)
+        end
+        grant
+      end
+
+      private
+
+      def target
+        Grant.where(owner: @owner).for_connector(@connector_class.connector_key).find(@grant_id)
+      end
+
+      def verify_snapshot!(grant)
+        unless grant.owner == @owner && grant.connector_key == @connector_class.connector_key.to_s &&
+               @fingerprint == self.class.fingerprint(grant)
+          raise Connectors::Error, "connection changed during authorization; start again"
+        end
+      end
+
+      def persist(grant, tokens, name)
+        account_id = @connector_class.external_account_id_from_credentials(tokens)
+        if grant.external_account_id.present? && account_id.present? && grant.external_account_id != account_id
+          raise Connectors::Error, "authorized account does not match this connection"
+        end
+
+        credentials = grant.stored_credentials_hash.merge(tokens)
+        grant.assign_attributes(
+          credentials: credentials,
+          status: :active,
+          expires_at: (Time.at(credentials["expires_at"]) if credentials["expires_at"]),
+          last_used_at: Time.current,
+          external_account_id: account_id.presence || grant.external_account_id
+        )
+        grant.display_name = name if name.present?
+        grant.save!
+        grant
+      end
+    end
+  end
+end

data/lib/connectors/oauth/pkce.rb

@@ -0,0 +1,32 @@
+require "securerandom"
+require "digest"
+require "base64"
+
+module Connectors
+  module OAuth
+    # RFC 7636 — Proof Key for Code Exchange. We generate a random
+    # `code_verifier`, derive `code_challenge = BASE64URL(SHA256(verifier))`
+    # (method `S256`), and embed the verifier in the signed OAuth state
+    # token so the callback can include it in the token exchange.
+    #
+    # n8n parity: `oauth.service.ts:578-586` — same `S256` derivation,
+    # verifier stashed in encrypted credential data until callback. We use
+    # the signed state token instead of a DB write so the flow stays
+    # stateless on the engine side.
+    module Pkce
+      module_function
+
+      VERIFIER_BYTES = 64
+
+      def generate
+        verifier  = base64url(SecureRandom.random_bytes(VERIFIER_BYTES))
+        challenge = base64url(Digest::SHA256.digest(verifier))
+        { verifier: verifier, challenge: challenge, method: "S256" }
+      end
+
+      def base64url(bytes)
+        Base64.urlsafe_encode64(bytes, padding: false)
+      end
+    end
+  end
+end

data/lib/connectors/oauth/revoke.rb

@@ -0,0 +1,72 @@
+require "faraday"
+require "uri"
+
+module Connectors
+  module OAuth
+    # RFC 7009 token revocation. POSTs `token=<access_token>` to the
+    # provider's revoke endpoint. The connector class declares the URL via
+    # `revoke_token_url "https://..."`; some providers want a different
+    # request shape (Google's revoke is `?token=`, etc.), so a connector
+    # can also override the whole call with a block:
+    #
+    #   revoke_token do |connector, grant|
+    #     connector.client.delete("oauth/tokens/#{grant.credentials_hash['access_token']}")
+    #   end
+    #
+    # n8n parity: per-provider, no centralized contract — n8n's oauth
+    # service implements it ad-hoc on a per-credential basis. We give
+    # connectors a single uniform DSL.
+    class Revoke
+      def self.call(connector_class, grant)
+        new(connector_class, grant).call
+      end
+
+      def initialize(connector_class, grant)
+        @connector_class = connector_class
+        @grant           = grant
+      end
+
+      def call
+        if (block = @connector_class.revoke_token_block)
+          @connector_class.new(@grant).instance_exec(@grant, &block)
+          return true
+        end
+
+        url = @connector_class.revoke_token_url or
+          raise Connectors::Error.new("#{@connector_class}: no revoke_token_url or revoke_token block declared")
+
+        token = @grant.credentials_hash["access_token"] || @grant.credentials_hash["refresh_token"]
+        raise Connectors::Error.new("grant has no access_token to revoke") if token.to_s.empty?
+
+        secrets = secrets_for_connector
+        body    = { token: token, client_id: secrets[:client_id], client_secret: secrets[:client_secret] }.compact
+
+        response = Faraday.post(url, URI.encode_www_form(body), {
+          "Content-Type" => "application/x-www-form-urlencoded",
+          "Accept"       => "application/json"
+        }) do |request|
+          request.options.open_timeout = ClientBuilder::DEFAULT_OPEN_TIMEOUT
+          request.options.timeout = ClientBuilder::DEFAULT_TIMEOUT
+        end
+
+        if response.status >= 400
+          raise Connectors::AuthenticationFailed.new(
+            "OAuth token revocation failed (#{response.status}): #{response.body}",
+            status: response.status,
+            body:   response.body
+          )
+        end
+
+        true
+      end
+
+      private
+
+      def secrets_for_connector
+        Connectors.configuration.oauth_credentials_for(@connector_class.connector_key)
+      rescue Connectors::Error
+        {}
+      end
+    end
+  end
+end

data/lib/connectors/oauth/state.rb

@@ -0,0 +1,41 @@
+require "securerandom"
+
+module Connectors
+  module OAuth
+    # Stateless CSRF token for the OAuth authorize → callback round trip.
+    # Carries the connector key, owner GlobalID, and an optional return-to URL,
+    # authenticated and encrypted so PKCE/OAuth1 secrets never appear in the
+    # authorization URL. Expires in 15 minutes. This is not a session cookie.
+    module State
+      module_function
+
+      EXPIRES_IN = 15.minutes
+      PURPOSE    = :connectors_oauth_state
+
+      def encode(connector_key:, owner_gid:, return_to: nil, extra: nil)
+        payload = {
+          "k" => connector_key.to_s,
+          "o" => owner_gid,
+          "r" => return_to,
+          "n" => SecureRandom.hex(16),
+          "t" => Time.now.to_i
+        }
+        payload["x"] = extra if extra.is_a?(Hash) && extra.any?
+        encryptor.encrypt_and_sign(payload, expires_in: EXPIRES_IN, purpose: PURPOSE)
+      end
+
+      def decode(token)
+        return nil unless token.is_a?(String) && token.present?
+        encryptor.decrypt_and_verify(token, purpose: PURPOSE).presence
+      rescue ActiveSupport::MessageEncryptor::InvalidMessage, ArgumentError
+        nil
+      end
+
+      def encryptor
+        cipher = "aes-256-gcm"
+        key = Rails.application.key_generator.generate_key(PURPOSE.to_s, ActiveSupport::MessageEncryptor.key_len(cipher))
+        ActiveSupport::MessageEncryptor.new(key, cipher: cipher, serializer: JSON)
+      end
+    end
+  end
+end

data/lib/connectors/oauth/token_exchange.rb

@@ -0,0 +1,69 @@
+require "faraday"
+require "uri"
+
+module Connectors
+  module OAuth
+    # Talks to the provider's token endpoint for both the authorization-code
+    # exchange (initial connection) and refresh-token grant (token rotation).
+    # Returns a normalized hash that can be merged directly into a Grant's
+    # credentials column.
+    class TokenExchange
+      def self.exchange_code(connector_class, code:, code_verifier: nil)
+        new(connector_class).exchange_code(code, code_verifier: code_verifier)
+      end
+
+      def self.refresh(connector_class, refresh_token:)
+        new(connector_class).refresh(refresh_token)
+      end
+
+      def initialize(connector_class)
+        @connector_class = connector_class
+        @config          = connector_class.oauth2_config or
+          raise Connectors::Error.new("#{connector_class}: oauth2 ... DSL not declared")
+        @secrets         = Connectors.configuration.oauth_credentials_for(connector_class.connector_key)
+      end
+
+      def exchange_code(code, code_verifier: nil)
+        # PKCE supplements client authentication for confidential clients.
+        params = {
+          grant_type:    "authorization_code",
+          code:          code,
+          redirect_uri:  redirect_uri
+        }
+        params[:code_verifier] = code_verifier if code_verifier
+        post_token(params)
+      end
+
+      def refresh(refresh_token)
+        post_token(
+          grant_type:    "refresh_token",
+          refresh_token: refresh_token
+        )
+      end
+
+      private
+
+      def post_token(params)
+        headers = {
+          "Content-Type" => "application/x-www-form-urlencoded",
+          "Accept"       => "application/json"
+        }
+        ClientAuthentication.apply(params, headers, secrets: @secrets, authentication: @config[:authentication])
+        response = Faraday.post(@config[:token_url], URI.encode_www_form(params.compact), headers) do |request|
+          request.options.open_timeout = ClientBuilder::DEFAULT_OPEN_TIMEOUT
+          request.options.timeout = ClientBuilder::DEFAULT_TIMEOUT
+        end
+
+        body = TokenResponse.parse(response)
+        @connector_class.post_token_exchange(body, TokenResponse.normalize(body))
+      end
+
+      # Must match the redirect_uri sent during the authorize leg or the
+      # provider rejects the exchange with `redirect_uri_mismatch`. Both
+      # legs read from the same config slot so they stay in lockstep.
+      def redirect_uri
+        Connectors.configuration.resolved_app_callback_url(@connector_class.connector_key)
+      end
+    end
+  end
+end