connectors 0.1.0

data/app/controllers/connectors/grants_controller.rb

@@ -0,0 +1,123 @@
+module Connectors
+  # Lists the current owner's authorized third-party accounts. The frontend
+  # uses this to render the "Connected accounts" picker on credential fields
+  # and the Settings → Connections page.
+  #
+  # Filter by connector with `?connector_key=slack`.
+  #
+  # Credentials are never serialized — only metadata (status, expiry, the
+  # provider-side account id, and the granted scope list).
+  class GrantsController < ApplicationController
+    rescue_from Connectors::Error,             with: :render_unauthorized
+    rescue_from ActiveRecord::RecordNotFound,  with: :render_not_found
+    rescue_from ArgumentError, with: :render_bad_request
+
+    # GET /connectors/grants
+    def index
+      owner  = current_owner!
+      grants = Grant.where(owner: owner)
+      grants = grants.for_connector(params[:connector_key]) if params[:connector_key].present?
+      render json: { grants: grants.order(updated_at: :desc).map { |g| serialize(g) } }
+    end
+
+    # POST /connectors/grants/:id/test
+    # Runs the connector's declared `test_request` against the live
+    # provider using THIS grant's credentials. Returns `{status, message}`
+    # — n8n parity (packages/cli/src/credentials/credentials.controller.ts:141-152).
+    def test
+      owner = current_owner!
+      grant = Grant.where(owner: owner).find(params[:id])
+      result = Connectors::CredentialTester.run(grant)
+      status_code = result[:status] == Connectors::CredentialTester::OK ? :ok : :unprocessable_content
+      render json: result, status: status_code
+    end
+
+    # POST /connectors/grants/:id/webhook_subscribe
+    # Runs the connector's `webhook_methods` create flow (skipping when
+    # check_exists already returns true). Manual entry point for Phase 6 —
+    # the workflow activation manager will call into this same lifecycle
+    # primitive (`Connectors::WebhookLifecycle.subscribe`) once it ships.
+    #
+    # Params:
+    #   webhook_name=:default — group name (multi-webhook providers)
+    #   hook_url=<override>   — defaults to the per-grant or app-level URL
+    def webhook_subscribe
+      owner = current_owner!
+      grant = Grant.where(owner: owner).find(params[:id])
+
+      name = (params[:webhook_name].presence || :default).to_sym
+      url  = params[:hook_url].presence || default_hook_url(grant)
+
+      result = Connectors::WebhookLifecycle.subscribe(grant, hook_url: url, webhook_name: name)
+      render json: result.merge(webhook_name: name, hook_url: url)
+    end
+
+    # DELETE /connectors/grants/:id/webhook_subscribe
+    def webhook_unsubscribe
+      owner = current_owner!
+      grant = Grant.where(owner: owner).find(params[:id])
+      name  = (params[:webhook_name].presence || :default).to_sym
+      result = Connectors::WebhookLifecycle.unsubscribe(grant, webhook_name: name)
+      render json: result.merge(webhook_name: name)
+    end
+
+    # POST /connectors/grants/:id/poll
+    # Runs the connector's `polling` block once. Manual harness for Phase 8 —
+    # the workflow-side scheduler will call into `Connectors::PollRunner.run`
+    # directly once it ships.
+    def poll
+      owner  = current_owner!
+      grant  = Grant.where(owner: owner).find(params[:id])
+      result = Connectors::PollRunner.run(grant, instance_key: params[:instance_key])
+      render json: result
+    end
+
+    private
+
+    def default_hook_url(grant)
+      base            = Connectors.configuration.host_base_url.to_s.chomp("/")
+      mount           = Connectors::Engine.mount_path
+      connector_class = Registry.fetch(grant.connector_key)
+      if connector_class.webhook_style == :app_level
+        "#{base}#{mount}/#{grant.connector_key}/webhook"
+      else
+        "#{base}#{mount}/#{grant.connector_key}/#{grant.id}/webhook"
+      end
+    end
+
+    def serialize(grant)
+      {
+        id:                  grant.id,
+        connector_key:       grant.connector_key,
+        display_name:        grant.display_name,
+        external_account_id: grant.external_account_id,
+        status:              grant.status,
+        expires_at:          grant.expires_at,
+        last_used_at:        grant.last_used_at,
+        scopes:              extract_scopes(grant)
+      }
+    end
+
+    # Most OAuth2 providers return scopes as a comma- or space-separated string
+    # in the token response and we store it verbatim. Normalize to an array so
+    # the frontend doesn't have to know the provider's separator convention.
+    def extract_scopes(grant)
+      raw = grant.credentials_hash["scope"]
+      return nil if raw.nil?
+      return raw if raw.is_a?(Array)
+      raw.to_s.split(/[,\s]+/).reject(&:empty?)
+    end
+
+    def render_unauthorized(exception)
+      render json: { error: exception.message }, status: :unauthorized
+    end
+
+    def render_not_found(exception)
+      render json: { error: exception.message }, status: :not_found
+    end
+
+    def render_bad_request(exception)
+      render json: { error: exception.message }, status: :bad_request
+    end
+  end
+end

data/app/controllers/connectors/mcp_controller.rb

@@ -0,0 +1,88 @@
+module Connectors
+  class McpController < ApplicationController
+    rescue_from ActiveRecord::RecordNotFound, with: :not_found
+    rescue_from MCP::Error, with: :mcp_error
+
+    def tools
+      render json: { tools: client.tools }
+    end
+
+    def call_tool
+      render json: client.call_tool(name: params.require(:name), arguments: json_object(:arguments))
+    end
+
+    def resume
+      render json: client.resume(interaction_id: params.require(:interaction_id), responses: json_object(:responses))
+    end
+
+    def authorize
+      grant = Grant.find(params[:id])
+      access = MCP::Access.new(grant: grant, actor: current_owner!, principals: current_principals)
+      access.require!(:owner)
+      if params[:authorization_context].present?
+        challenge = MCP::AuthorizationContext.decode(params[:authorization_context], access: access)
+        return render json: { authorization_url: authorization.start(challenge: challenge) }
+      end
+      # Challenge data is obtained from the MCP endpoint, not supplied as arbitrary URLs by the caller.
+      service = client
+      challenge = begin
+        service.tools
+        {}
+      rescue MCP::AuthorizationRequired => error
+        error.challenge
+      end
+      render json: { authorization_url: authorization.start(challenge: challenge) }
+    end
+
+    def callback
+      state = params.require(:state)
+      record = McpAuthorization.find_by!(state_digest: Digest::SHA256.hexdigest(state))
+      service = MCP::Authorization.new(grant: record.grant, actor: current_owner!, principals: current_principals)
+      service.complete(state: state, code: params[:code], iss: params[:iss], error: params[:error])
+      render json: { status: "authorized" }
+    end
+
+    private
+
+    def json_object(key)
+      value = params[key]
+      raise MCP::ValidationError, "#{key} must be an object" unless value.is_a?(ActionController::Parameters)
+      value.to_unsafe_h
+    end
+
+    def client
+      MCP::Client.new(grant: Grant.find(params[:id]), actor: current_owner!, principals: current_principals)
+    end
+
+    def authorization
+      MCP::Authorization.new(grant: Grant.find(params[:id]), actor: current_owner!, principals: current_principals)
+    end
+
+    def mcp_error(error)
+      status, kind = case error
+      when MCP::AccessDenied then [ :forbidden, "access_denied" ]
+      when MCP::AuthorizationRequired then [ :unauthorized, "authorization_required" ]
+      when MCP::ConfigurationRequired then [ :unprocessable_content, "configuration_required" ]
+      when MCP::ValidationError then [ :unprocessable_content, "validation_error" ]
+      when MCP::ProtocolError then [ :bad_gateway, "protocol_error" ]
+      when MCP::HTTPError
+        error.status == 429 ? [ :too_many_requests, "rate_limited" ] : [ :bad_gateway, "transport_error" ]
+      else [ :bad_gateway, "transport_error" ]
+      end
+      body = { error: { type: kind, message: error.message } }
+      if kind == "rate_limited" && (retry_after = error.retry_after)
+        response.headers["Retry-After"] = retry_after
+        body[:error][:retry_after] = retry_after
+      end
+      if error.is_a?(MCP::AuthorizationRequired)
+        grant = Grant.find(params[:id])
+        body[:authorization_context] = MCP::AuthorizationContext.encode(grant: grant, challenge: error.challenge, fingerprint: error.fingerprint)
+      end
+      render json: body, status: status
+    end
+
+    def not_found
+      head :not_found
+    end
+  end
+end

data/app/controllers/connectors/oauth_controller.rb

@@ -0,0 +1,134 @@
+require "global_id"
+
+module Connectors
+  class OAuthController < ApplicationController
+    rescue_from Connectors::Error, with: :render_auth_error
+    rescue_from ActiveRecord::RecordNotFound, Connectors::UnknownConnector, with: :render_not_found
+
+    # Omit grant_id to connect a new account; supply it to reconnect an owned
+    # grant. Both popup and redirect entry points use the same authorization.
+    def authorize
+      start_authorization(json: false)
+    end
+
+    def authorize_json
+      start_authorization(json: true)
+    end
+
+    # Split frontend/backend completion. Authorization is carried by the
+    # authenticated, encrypted state issued to the owner at the start.
+    def exchange
+      state = OAuth::State.decode(params[:state])
+      return invalid_state if state.nil?
+
+      grant = complete_authorization(state)
+      render json: grant_payload(grant).merge(
+        name: grant.display_name || "#{grant.connector_key} ##{grant.id}",
+        external_account_id: grant.external_account_id
+      )
+    end
+
+    def callback
+      state = OAuth::State.decode(params[:state])
+      return invalid_state if state.nil? || state["k"] != params[:connector_key].to_s
+
+      grant = complete_authorization(state)
+      if state["r"].present?
+        redirect_to state["r"], allow_other_host: true
+      else
+        render json: grant_payload(grant)
+      end
+    end
+
+    def revoke
+      grant = find_visible_grant!(params[:id], min_role: :owner)
+      # Serialize revocation with refresh/reconnection on the same grant.
+      grant.with_lock do
+        require_grant_role!(grant, :owner)
+        OAuth::Revoke.call(Registry.fetch(grant.connector_key), grant)
+        grant.update!(status: :revoked)
+      end
+      render json: { grant_id: grant.id, status: grant.status }
+    end
+
+    private
+
+    def start_authorization(json:)
+      klass = Registry.fetch(params[:connector_key])
+      owner = current_owner!
+      grant = Grant.where(owner: owner).for_connector(klass.connector_key).find(params[:grant_id]) if params[:grant_id].present?
+
+      if klass.oauth2_config&.dig(:grant_type) == "clientCredentials"
+        writer = OAuth::GrantWriter.new(owner: owner, connector_class: klass,
+          grant_id: grant&.id, fingerprint: (OAuth::GrantWriter.fingerprint(grant) if grant))
+        connected = writer.call(OAuth::ClientCredentials.exchange(klass), name: params[:name])
+        return render json: grant_payload(connected)
+      end
+
+      url = if klass.oauth1_config
+        oauth1_authorize_url(klass, owner, grant)
+      else
+        OAuth::AuthorizeUrl.for(klass, owner: owner, grant: grant,
+          return_to: params[:return_to], scope: params[:scope], name: params[:name])
+      end
+
+      if json
+        render json: { authorize_url: url, connector_key: klass.connector_key.to_s }
+      else
+        redirect_to url, allow_other_host: true
+      end
+    end
+
+    def oauth1_authorize_url(klass, owner, grant)
+      callback_url = Connectors.configuration.resolved_app_callback_url(klass.connector_key)
+      token = OAuth1.request_token(klass, callback_url: callback_url)
+      extras = { "ts" => token["oauth_token_secret"], "n" => params[:name] }
+      extras.merge!("g" => grant.id, "v" => OAuth::GrantWriter.fingerprint(grant)) if grant
+      state = OAuth::State.encode(connector_key: klass.connector_key,
+        owner_gid: owner.to_global_id.to_s, return_to: params[:return_to], extra: extras)
+      uri = URI.parse(klass.oauth1_config[:authorize_url])
+      uri.query = URI.encode_www_form(URI.decode_www_form(uri.query.to_s) +
+        [ [ "oauth_token", token["oauth_token"] ], [ "state", state ] ])
+      uri.to_s
+    end
+
+    def complete_authorization(state)
+      klass = Registry.fetch(state["k"])
+      owner = locate_owner(state["o"])
+      raise ActiveRecord::RecordNotFound, "owner_not_found" unless owner
+
+      writer = OAuth::GrantWriter.new(owner: owner, connector_class: klass,
+        grant_id: state.dig("x", "g"), fingerprint: state.dig("x", "v"))
+      writer.validate!
+      tokens = if klass.oauth1_config
+        OAuth1.exchange_access_token(klass, oauth_token: params[:oauth_token],
+          oauth_verifier: params[:oauth_verifier], oauth_token_secret: state.dig("x", "ts"))
+      else
+        OAuth::TokenExchange.exchange_code(klass, code: params[:code], code_verifier: state.dig("x", "cv"))
+      end
+      writer.call(tokens, name: state.dig("x", "n"))
+    end
+
+    def locate_owner(gid)
+      GlobalID::Locator.locate(gid)
+    rescue ActiveRecord::RecordNotFound
+      nil
+    end
+
+    def grant_payload(grant)
+      { grant_id: grant.id, connector_key: grant.connector_key, status: grant.status }
+    end
+
+    def invalid_state
+      render json: { error: "invalid_state" }, status: :unauthorized
+    end
+
+    def render_not_found(exception)
+      render json: { error: exception.message }, status: :not_found
+    end
+
+    def render_auth_error(exception)
+      render json: { error: exception.message }, status: :unauthorized
+    end
+  end
+end

data/app/controllers/connectors/types_controller.rb

@@ -0,0 +1,144 @@
+module Connectors
+  # Catalog of every connector class registered in the engine. Read by the
+  # frontend at startup to render the "Add credential" form, the connect-OAuth
+  # popup, the credential picker on nodes — purely by reading this metadata.
+  # No per-connector frontend logic.
+  #
+  # Response shape mirrors n8n's `ICredentialType` description (n8n source:
+  # packages/workflow/src/interfaces.ts:356-382) so a single frontend renderer
+  # handles every connector. Returns only static metadata — never any secrets
+  # or per-user state.
+  class TypesController < ApplicationController
+    # GET /connectors/types
+    def index
+      types = Registry.all.sort_by { |key, _| key.to_s }.map { |key, klass| serialize(key, klass) }
+      render json: { types: types }
+    end
+
+    # GET /connectors/types/:name
+    def show
+      klass = Registry.fetch(params[:name])
+      render json: serialize(klass.connector_key, klass)
+    rescue Connectors::UnknownConnector => e
+      render json: { error: e.message }, status: :not_found
+    end
+
+    private
+
+    # The OAuth provider's "Authorized Redirect URI". This MUST match what
+    # `AuthorizeUrl` and `TokenExchange` actually send — both read from
+    # `Connectors.configuration.resolved_app_callback_url(...)`. Surfacing a
+    # different value here would mislead admins into registering a URL the
+    # engine never uses.
+    def redirect_uri_for(connector_key)
+      Connectors.configuration.resolved_app_callback_url(connector_key)
+    rescue Connectors::Error
+      # `host_base_url` not configured — return the engine's own callback
+      # path so introspection still works in headless setups.
+      "#{Connectors::Engine.mount_path}/#{connector_key}/callback"
+    end
+
+    def serialize(key, klass)
+      schema = klass.credential_schema
+
+      {
+        # `name` is the n8n vocabulary for the machine identifier; `display_name`
+        # is the picker label. We keep `key`/`label` as aliases for back-compat
+        # with the existing /grants response — frontend should prefer the n8n
+        # names going forward.
+        name:              key.to_s,
+        display_name:      klass.display_name || key.to_s.humanize,
+        key:               key.to_s,                                       # @deprecated — use `name`
+        label:             klass.display_name || key.to_s.humanize,        # @deprecated — use `display_name`
+        icon:              klass.icon,
+        icon_color:        klass.icon_color,
+        documentation_url: klass.documentation_url,
+        # URL to an LLM-optimized docs bundle (provider's `llms.txt` /
+        # `llms-full.txt`, per llmstxt.org). Lets agents + frontend tools
+        # fetch authoritative API behavior without scraping HTML.
+        llm_docs:          klass.llm_docs,
+        # Optional markdown the frontend renders at the top of the
+        # "Add connection" dialog. Backend-driven: nil when the
+        # connector doesn't need to walk the user through setup
+        # (e.g. Gmail's OAuth dance is self-explanatory); populated
+        # for connectors where the user needs to generate an API key
+        # or install an app first (e.g. Resend).
+        instructions:      klass.instructions,
+
+        # n8n inheritance chain. Empty array when the credential type stands
+        # alone (e.g., API-key connectors). Frontend can fetch the parent's
+        # schema via `/connectors/types/:parent` OR rely on the resolved
+        # `properties` array below which already merges parent + own.
+        extends:          schema ? schema.extends.map(&:to_s) : [],
+        properties:       schema ? schema.resolved_fields.map(&:to_property) : [],
+
+        # Declarative auth injection — mirrors n8n's `IAuthenticateGeneric`
+        # at packages/workflow/src/interfaces.ts:278-288. Reads the resolved
+        # config (connector-level override OR inherited from the credential
+        # type via `extends`). nil when the connector still uses the
+        # imperative `api_key_in` shim AND no parent declared one.
+        authenticate:     klass.resolved_authenticate_config,
+        # n8n's `genericAuth: boolean` (`interfaces.ts:379`). True when the
+        # connector itself flips `generic_auth!` OR when it extends a schema
+        # that already does (HttpBearerAuth etc.).
+        generic_auth:     klass.generic_auth?,
+
+        # n8n's `supportedNodes: string[]` (`interfaces.ts:381`). Empty array
+        # means "no restriction" — same default as n8n. The frontend uses
+        # this to filter the credential picker per node type.
+        supported_nodes:  klass.supported_nodes.map(&:to_s),
+
+        # n8n's `httpRequestNode: ICredentialHttpRequestNode` (interfaces.ts:380,
+        # union shape at :350-354). Tells the generic HTTP-Request node's
+        # credential picker how to label + link this credential. nil when the
+        # connector hasn't declared it.
+        http_request_node: klass.http_request_node,
+
+        # n8n's `__overwrittenProperties: string[]` (`interfaces.ts:382`;
+        # populated at `frontend.service.ts:681-705`). Field names whose
+        # values are sourced from the external secrets manager — the editor
+        # renders them locked / hidden. Empty array when no vault is
+        # configured for this connector type.
+        __overwritten_properties: Connectors.configuration.managed_fields_for(key),
+
+        # n8n's `__skipManagedCreation` (frontend.service.ts:707-711). When
+        # true the editor hides the "Use external secret" toggle.
+        __skip_managed_creation: klass.skip_managed_creation?,
+
+        # Action manifest — what this connector can DO with a credential.
+        # Each entry includes its own typed `properties` (input schema), an
+        # optional `output` schema, and metadata for the picker UI. Frontend
+        # browses these at design time; runtime invocation goes through
+        # `POST /credentials/:id/actions/:name`. Empty array when the
+        # connector hasn't declared any actions yet.
+        actions: klass.actions.map(&:to_manifest),
+
+        # Connector capabilities — orthogonal to credentials. Lives in its own
+        # block so frontend code that only cares about credential rendering
+        # can ignore it. For OAuth connectors, `redirect_uri` is the URL the
+        # admin must paste into the provider's app console (computed from the
+        # host's base URL — n8n does the same server-side at
+        # packages/cli/src/oauth/oauth.service.ts:528,690).
+        connector: {
+          base_url:      klass.base_url,
+          webhook_style: klass.webhook_style.to_s,
+          rate_limit:    klass.rate_limit_config,
+          authorize_url:      klass.oauth2_config ? "#{Connectors::Engine.mount_path}/#{key}/authorize"      : nil,
+          authorize_json_url: klass.oauth2_config ? "#{Connectors::Engine.mount_path}/#{key}/authorize.json" : nil,
+          redirect_uri:  klass.mcp? ? Connectors.configuration.resolved_mcp_callback_url : (klass.oauth2_config ? redirect_uri_for(key) : nil),
+          mcp: mcp_metadata(klass),
+          # Frontend gates the "Test connection" button on this flag.
+          test_supported: !klass.test_request_config.nil?
+        }
+      }
+    end
+
+    def mcp_metadata(klass)
+      return unless klass.mcp?
+      base = "#{Connectors::Engine.mount_path}/credentials/:id/mcp"
+      klass.mcp_config.merge("protocol_version" => MCP::PROTOCOL_VERSION,
+        "tools_url" => "#{base}/tools", "call_url" => "#{base}/tools/call",
+        "resume_url" => "#{base}/interactions/resume", "authorize_url" => "#{base}/authorize")
+    end
+  end
+end

data/app/controllers/connectors/webhooks_controller.rb

@@ -0,0 +1,105 @@
+module Connectors
+  class WebhooksController < ApplicationController
+    rescue_from Connectors::UnknownConnector,           with: :render_not_found
+    rescue_from ActiveRecord::RecordNotFound,           with: :render_not_found
+    rescue_from Connectors::Webhooks::SignatureInvalid, with: :render_unauthorized
+
+    # POST /:connector_key/webhook                 (app-level: grant resolved from payload)
+    # POST /:connector_key/:grant_id/webhook       (grant_id explicit in URL)
+    #
+    # Providers like Slack only allow one webhook URL per app — for those,
+    # leave grant_id out and implement Connector.resolve_grant_from_webhook
+    # to look up the grant by the payload's team/account id.
+    def receive
+      connector_class = Registry.fetch(params[:connector_key])
+      payload         = request_payload
+
+      grant = params[:grant_id].present? ? Grant.for_connector(connector_class.connector_key).find(params[:grant_id]) : nil
+
+      verify_signature!(connector_class, grant)
+
+      # URL-verification ping (Slack et al.) — short-circuit before grant lookup.
+      if (challenge = connector_class.webhook_challenge(payload))
+        return render(json: challenge)
+      end
+
+      grant ||= connector_class.resolve_grant_from_webhook(payload, request)
+      if grant.nil? || grant.connector_key != connector_class.connector_key.to_s
+        return render(json: { error: "no matching grant for webhook" }, status: :not_found)
+      end
+
+      external_id = extract_external_event_id(payload)
+      if external_id.present? &&
+         (existing = WebhookEvent.find_by(connector_key: grant.connector_key, external_event_id: external_id))
+        return render(json: { event_id: existing.id, status: "duplicate" }, status: :ok)
+      end
+
+      event = WebhookEvent.create!(
+        grant:             grant,
+        connector_key:     grant.connector_key,
+        external_event_id: external_id,
+        payload:           payload,
+        raw_body:          request.raw_post,
+        headers:           inbound_headers,
+        query:             request.query_parameters.to_h,
+        webhook_name:      (params[:webhook_name].presence || "default").to_s,
+        signature:         signature_header,
+        received_at:       Time.current,
+        status:            :received
+      )
+
+      DeliverWebhookJob.perform_later(event.id)
+      render json: { event_id: event.id, status: "accepted" }, status: :accepted
+    end
+
+    private
+
+    def verify_signature!(connector_class, grant)
+      verifier = connector_class.webhook_verifier
+      return if verifier.nil?
+      verifier.verify!(grant, request)
+    end
+
+    def request_payload
+      ct = request.content_type.to_s
+      if ct.include?("json")
+        body = request.raw_post
+        body.empty? ? {} : (JSON.parse(body) rescue {})
+      else
+        request.request_parameters.to_unsafe_h
+      end
+    end
+
+    def extract_external_event_id(payload)
+      return nil unless payload.is_a?(Hash)
+      payload["event_id"] || payload["id"] || payload.dig("event", "id")
+    end
+
+    def signature_header
+      request.headers["X-Slack-Signature"]      ||
+        request.headers["Stripe-Signature"]     ||
+        request.headers["X-Hub-Signature-256"]  ||
+        request.headers["X-Signature"]          ||
+        request.headers["Signature"]
+    end
+
+    # Capture every HTTP_* header on the inbound request, normalized to
+    # lowercase + dashed keys (`http_x_hub_signature` → `x-hub-signature`),
+    # so the n8n-style `ctx.headers["stripe-signature"]` access works
+    # without callers having to know about Rack's mangling.
+    def inbound_headers
+      request.headers.env.each_with_object({}) do |(k, v), out|
+        next unless k.start_with?("HTTP_")
+        name = k.sub("HTTP_", "").downcase.tr("_", "-")
+        out[name] = v.is_a?(String) ? v : v.to_s
+      end.merge(
+        # Content-Type/Length aren't prefixed `HTTP_` in Rack
+        "content-type"   => request.content_type.to_s,
+        "content-length" => request.content_length.to_s
+      ).reject { |_, v| v.nil? || v.empty? }
+    end
+
+    def render_not_found(e);    render(json: { error: e.message }, status: :not_found);    end
+    def render_unauthorized(e); render(json: { error: e.message }, status: :unauthorized); end
+  end
+end

data/app/jobs/connectors/application_job.rb

@@ -0,0 +1,4 @@
+module Connectors
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/jobs/connectors/deliver_webhook_job.rb

@@ -0,0 +1,27 @@
+module Connectors
+  class DeliverWebhookJob < ApplicationJob
+    queue_as :default
+
+    discard_on ActiveJob::DeserializationError
+
+    def perform(event_id)
+      event = WebhookEvent.find(event_id)
+      return if event.processed? || event.ignored?
+
+      # Phase 7: always hand the connector a `WebhookContext` (n8n parity
+      # with `IWebhookFunctions`). The context still exposes `.event` /
+      # `.payload_hash` so handlers written against the old `event` arg
+      # keep working without changes — the new accessors are additive.
+      event.grant.connector.handle_webhook(Connectors::WebhookContext.new(event))
+      event.update!(status: :processed, processed_at: Time.current, error_message: nil)
+
+      Connectors.configuration.on_webhook&.call(event)
+    rescue => e
+      event&.update_columns(
+        status:        WebhookEvent.statuses[:failed],
+        error_message: "#{e.class}: #{e.message}".byteslice(0, 1000)
+      )
+      raise
+    end
+  end
+end

data/app/jobs/connectors/poll_job.rb

@@ -0,0 +1,49 @@
+module Connectors
+  # Periodic poller for connectors that opt into polling. Two modes:
+  #
+  #   PollJob.perform_later          # fan-out: enqueues one PollJob per eligible grant
+  #   PollJob.perform_later(grant.id) # poll one grant
+  #
+  # In production, schedule the fan-out from Solid Queue's recurring config:
+  #
+  #   # config/recurring.yml (in the host app)
+  #   production:
+  #     poll_connectors:
+  #       class: Connectors::PollJob
+  #       queue: default
+  #       schedule: every 5 minutes
+  #
+  # Grants whose connector class hasn't overridden #poll are skipped so we
+  # don't enqueue dead work.
+  class PollJob < ApplicationJob
+    queue_as :default
+
+    def perform(grant_id = nil)
+      grant_id ? poll_one(grant_id) : fan_out
+    end
+
+    def self.poll_implemented?(connector_key)
+      klass = Registry.fetch(connector_key)
+      klass.instance_method(:poll).owner != Connectors::Connector
+    rescue Connectors::UnknownConnector
+      false
+    end
+
+    private
+
+    def fan_out
+      Grant.active.find_each do |grant|
+        next unless self.class.poll_implemented?(grant.connector_key)
+        self.class.perform_later(grant.id)
+      end
+    end
+
+    def poll_one(grant_id)
+      grant = Grant.find(grant_id)
+      return unless grant.active?
+
+      grant.connector.poll
+      grant.update_columns(last_used_at: Time.current)
+    end
+  end
+end

data/app/models/connectors/application_record.rb

@@ -0,0 +1,5 @@
+module Connectors
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end