connectors 0.1.0

data/app/connectors/resend/connector.rb

@@ -0,0 +1,218 @@
+module Resend
+  # Resend (https://resend.com) — transactional email API.
+  # https://resend.com/docs/api-reference/emails/send-email
+  #
+  # Auth: bearer API key (`re_xxx...`). Single credential field; no OAuth.
+  # The host creates a Grant out-of-band (admin paste, env-driven seed,
+  # whatever your host wires up).
+  class Connector < Connectors::Connector
+    connector key:               :resend,
+              auth:              :api_key,
+              base_url:          "https://api.resend.com",
+              display_name:      "Resend",
+              icon:              "https://cdn.resend.com/brand/resend-icon-blacka.svg",
+              icon_color:        "#000000",
+              documentation_url: "https://resend.com/docs/api-reference/emails/send-email",
+              llm_docs:          "https://resend.com/docs/llms-full.txt",
+              instructions:      <<~MD
+                **Generate an API key:**
+
+                1. Sign in at [resend.com/api-keys](https://resend.com/api-keys).
+                2. Click **Create API Key** and give it a name.
+                3. Choose **Full Access** so the "Test connection" button works (Sending Access keys can only `POST /emails`, so they fail every read endpoint).
+                4. Copy the key — it starts with `re_` — and paste it below.
+
+                Keys can be revoked any time from the same dashboard.
+              MD
+
+    credentials do
+      field :api_key,
+            type:         "string",
+            display_name: "API Key",
+            required:     true,
+            secret:       true,
+            placeholder:  "re_...",
+            description:  "Generate at https://resend.com/api-keys."
+    end
+
+    # Phase 1 — declarative auth injection (mirrors n8n's HttpBearerAuth at
+    # packages/nodes-base/credentials/HttpBearerAuth.credentials.ts:38-45).
+    # The `={{...}}` template is resolved per-request from the Grant's
+    # credentials hash by `Middleware::AuthenticateGeneric`.
+    authenticate type: :generic, properties: {
+      headers: { "Authorization" => "=Bearer {{$credentials.api_key}}" }
+    }
+
+    # Resend's documented rate limit is 2 requests per second.
+    # https://resend.com/docs/api-reference/introduction#rate-limit
+    rate_limit 2, per: 1.second
+
+    # ─── actions ─────────────────────────────────────────────────────────
+    # Declarative action manifest. Discoverable via /connectors/types/resend
+    # → `actions`, invokable via POST /connectors/credentials/:id/actions/send_email.
+    # The execute block runs in connector-instance context so we can delegate
+    # straight to the existing `send_email` method below (also kept callable
+    # directly so spec tests + the workflow executor can use either entry
+    # point).
+    action :send_email,
+           display_name: "Send Email",
+           description:  "Send a transactional email through Resend." do
+      field :from,
+            type:         "string",
+            display_name: "From",
+            required:     true,
+            placeholder:  "Updates <updates@yourdomain.com>",
+            description:  "Sender — must be a verified domain in Resend."
+
+      field :to,
+            type:         "string",
+            display_name: "To",
+            required:     true,
+            type_options: { multiple_values: true },
+            description:  "One or more recipient email addresses."
+
+      field :subject,
+            type:         "string",
+            display_name: "Subject",
+            required:     true
+
+      field :html,
+            type:         "string",
+            display_name: "HTML Body",
+            type_options: { editor: "html" },
+            description:  "HTML content. Either html or text is required."
+
+      field :text,
+            type:         "string",
+            display_name: "Plain Text Body",
+            type_options: { rows: 4 },
+            description:  "Plain text content. Either html or text is required."
+
+      field :cc,
+            type:         "string",
+            display_name: "CC",
+            type_options: { multiple_values: true }
+
+      field :bcc,
+            type:         "string",
+            display_name: "BCC",
+            type_options: { multiple_values: true }
+
+      field :reply_to,
+            type:         "string",
+            display_name: "Reply To",
+            type_options: { multiple_values: true }
+
+      field :scheduled_at,
+            type:         "string",
+            display_name: "Scheduled At",
+            placeholder:  "in 1 hour",
+            description:  "ISO 8601 timestamp OR Resend's natural-language form (e.g. 'in 1 hour')."
+
+      field :tags,
+            type:         "json",
+            display_name: "Tags",
+            description:  "Array of `{name, value}` tag objects."
+
+      field :attachments,
+            type:         "json",
+            display_name: "Attachments",
+            description:  "Array of `{filename, content, path?, content_type?}` objects."
+
+      field :headers,
+            type:         "json",
+            display_name: "Custom Headers",
+            description:  "Hash of header name → value."
+
+      output do
+        field :id, type: "string", description: "Resend message id."
+      end
+
+      execute do |input|
+        send_email(**input.symbolize_keys)
+      end
+    end
+
+    # "Test connection" hits Resend's `GET /domains` — a cheap, idempotent
+    # read that succeeds for any **Full Access** API key.
+    #
+    # CAVEAT, per Resend's docs (https://resend.com/docs/dashboard/api-keys):
+    #   - "Full Access"    keys can create/delete/get/update any resource
+    #   - "Sending Access" keys can ONLY POST /emails (send) — no reads
+    #
+    # Sending-Access keys will return 401 on EVERY GET endpoint Resend
+    # exposes, including this one. So this test reliably verifies Full
+    # Access keys; Sending-Access keys will always show as "failed" here
+    # even when the key works fine for sending. The only way to truly
+    # test a Sending-Access key is to actually send an email — which
+    # we don't do because it's destructive.
+    test_request method: :get, url: "domains"
+
+    # Send a transactional email. Returns Resend's `{ "id" => "..." }` payload
+    # so downstream nodes can reference the message id.
+    #
+    #   from:     "Updates <updates@yourdomain.com>"
+    #   to:       "user@example.com" | [ "a@example.com", "b@example.com" ]
+    #   reply_to: same — single string OR array
+    #
+    # `html` and `text` are both optional but at least one must be present —
+    # Resend rejects emails with no body. Logical 200-with-error responses
+    # are promoted to Connectors::ApiError so the executor records the
+    # failure on the Step.
+    def send_email(from:, to:, subject:, html: nil, text: nil,
+                   cc: nil, bcc: nil, reply_to: nil, tags: nil,
+                   scheduled_at: nil, attachments: nil, headers: nil)
+      raise Connectors::ApiError.new("send_email requires html or text") if html.nil? && text.nil?
+
+      body = {
+        "from"    => from,
+        "to"      => Array(to),
+        "subject" => subject
+      }
+      body["html"]         = html              if html
+      body["text"]         = text              if text
+      body["cc"]           = Array(cc)         if cc
+      body["bcc"]          = Array(bcc)        if bcc
+      body["reply_to"]     = Array(reply_to)   if reply_to    # Resend expects string[]
+      body["tags"]         = tags              if tags
+      body["scheduled_at"] = scheduled_at      if scheduled_at
+      body["attachments"]  = attachments       if attachments
+      body["headers"]      = headers           if headers
+
+      response = client.post("emails", body)
+      payload  = response.body
+
+      if response.status >= 400 || resend_error?(payload)
+        raise Connectors::ApiError.new(
+          "Resend send_email failed: #{resend_error_message(payload) || payload.inspect}",
+          status: response.status,
+          body:   payload
+        )
+      end
+
+      payload
+    end
+
+    private
+
+    # Resend returns errors in two distinct shapes depending on the failure
+    # mode (per Resend's own docs at resend.com/docs/api-reference/errors):
+    #
+    #   1. Top-level:  `{ "name": "missing_required_field", "message": "...",
+    #                     "statusCode": 422 }`
+    #   2. Nested:     `{ "error": { "message": "..." } }`
+    #
+    # A 200-but-failed response carries shape (1). A non-2xx may carry
+    # either. Both have to be recognized or we'd silently treat broken
+    # sends as successful.
+    def resend_error?(payload)
+      return false unless payload.is_a?(Hash)
+      payload.key?("error") || payload.key?("name") || payload.key?("statusCode")
+    end
+
+    def resend_error_message(payload)
+      return nil unless payload.is_a?(Hash)
+      payload.dig("error", "message") || payload["message"]
+    end
+  end
+end

data/app/controllers/concerns/connectors/grant_access.rb

@@ -0,0 +1,43 @@
+module Connectors
+  # Shared access boundary for every credential endpoint. The host supplies
+  # identities; the engine applies the same roles to CRUD, actions and OAuth.
+  module GrantAccess
+    extend ActiveSupport::Concern
+
+    private
+
+    ROLE_RANK = GrantPolicy::ROLE_RANK
+
+    def current_owner!
+      @connectors_owner ||= Connectors.configuration.resolve_owner(self) or
+        raise Connectors::Error, "current_owner_resolver returned nil"
+    end
+
+    def current_principals
+      @connectors_principals ||= Connectors.configuration.resolve_principals(self) || []
+    end
+
+    def visible_grants
+      owner = current_owner!
+      shared_ids = CredentialShare.for_principals(current_principals).select(:grant_id)
+      Grant.where(owner: owner).or(Grant.where(id: shared_ids))
+    end
+
+    def find_visible_grant!(id, min_role: :viewer)
+      grant = visible_grants.find(id)
+      require_grant_role!(grant, min_role)
+      grant
+    end
+
+    def require_grant_role!(grant, min_role)
+      role = role_for(grant, owner: current_owner!)
+      if role.nil? || ROLE_RANK.fetch(role) < ROLE_RANK.fetch(min_role.to_s)
+        raise Connectors::Error, "credential #{grant.id} requires #{min_role} role (you have #{role})"
+      end
+    end
+
+    def role_for(grant, owner:)
+      GrantPolicy.role_for(grant, owner: owner, principals: current_principals)
+    end
+  end
+end

data/app/controllers/connectors/actions_controller.rb

@@ -0,0 +1,66 @@
+module Connectors
+  # HTTP surface for invoking a connector's declared actions.
+  #
+  #   POST /connectors/credentials/:id/actions/:name
+  #   { "data": { "to": "alice@example.com", "subject": "Hi", "html": "..." } }
+  #
+  # Looks up the Grant (scoped to the current owner + any shares), resolves
+  # the action on the grant's connector class, validates the input against
+  # the action's param schema, then dispatches through `ActionRunner`. The
+  # response envelope is always `{ status: "ok"|"error", action:, ... }` so
+  # frontends and workflow executors consume the same shape.
+  #
+  # n8n parity: this is the moral equivalent of the executor's per-node
+  # `execute()` step (packages/core/src/node-execute-functions.ts) reachable
+  # over HTTP. The workflow engine in `automations/` will eventually call
+  # `ActionRunner.call(grant, action, input)` directly without going
+  # through HTTP — same path, no controller in the loop.
+  class ActionsController < ApplicationController
+    # Order matters: Rails `rescue_from` iterates in REVERSE declaration
+    # order, so the more-specific subclasses must be declared AFTER
+    # `Connectors::Error` to be matched first. UnknownAction is a
+    # Connectors::Error subclass — without its own handler, the generic
+    # Error path would return 401 instead of 404.
+    rescue_from Connectors::Error,            with: :render_unauthorized
+    rescue_from ActiveRecord::RecordNotFound, with: :render_not_found
+    rescue_from Connectors::UnknownAction,    with: :render_not_found
+
+    # GET /connectors/credentials/:id/actions
+    # Lists the actions available on the grant's connector. Same data as
+    # /connectors/types/:name → actions[], but resolved against the actual
+    # grant so the frontend can render an "actions for this connection"
+    # picker without re-fetching the catalog.
+    def index
+      grant = find_visible_grant!(params[:id])
+      render json: { actions: grant.connector.class.actions.map(&:to_manifest) }
+    end
+
+    # POST /connectors/credentials/:id/actions/:name
+    # Body: { data: {...} }   — the action's input params.
+    def create
+      grant = find_visible_grant!(params[:id], min_role: :editor)
+      input = (params[:data] || {}).to_unsafe_h
+      result = Connectors::ActionRunner.call(grant, params[:name], input)
+
+      status_code =
+        if result[:status] == Connectors::ActionRunner::OK
+          :ok
+        else
+          case result.dig(:error, :type)
+          when "invalid_params"         then :unprocessable_content
+          when "authentication_failed"  then :unauthorized
+          when "forbidden"              then :forbidden
+          when "rate_limited"           then :too_many_requests
+          else                               :bad_gateway
+          end
+        end
+
+      render json: result, status: status_code
+    end
+
+    private
+
+    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/controllers/connectors/application_controller.rb

@@ -0,0 +1,5 @@
+module Connectors
+  class ApplicationController < ActionController::API
+    include GrantAccess
+  end
+end

data/app/controllers/connectors/credentials_controller.rb

@@ -0,0 +1,245 @@
+module Connectors
+  # n8n-shaped credential CRUD. Underneath, a "credential" is a Grant — but
+  # this controller exposes it under the vocabulary the frontend uses
+  # (matches packages/cli/src/credentials/credentials.controller.ts:67-411).
+  #
+  # The paste-the-key flow lives here: `POST /credentials` with `{type,
+  # name, data}` creates a Grant directly without the OAuth dance.
+  # OAuth-issued grants continue to flow through OAuthController#callback
+  # and show up in this list automatically.
+  class CredentialsController < ApplicationController
+    # Order matters: Rails `rescue_from` iterates in REVERSE declaration
+    # order, so the more-specific subclasses must be declared AFTER
+    # `Connectors::Error` to be matched first.
+    rescue_from Connectors::Error,              with: :render_unauthorized
+    rescue_from ActiveRecord::RecordNotFound,   with: :render_not_found
+    rescue_from Connectors::UnknownConnector,   with: :render_not_found
+    rescue_from MCP::ValidationError, MCP::ConfigurationRequired do |error|
+      render json: { error: error.message }, status: :unprocessable_content
+    end
+
+    # GET /connectors/credentials
+    #   ?type=resend                # filter by connector type
+    #   ?include_data=true          # owner-only secrets; MCP public config only
+    #
+    # Returns the union of: credentials this owner owns + credentials shared
+    # with any of the requester's principals (User, Team, Project — whatever
+    # the host's `principal_resolver` returns). n8n parity:
+    # enterprise/credentials.controller.ee.ts.
+    def index
+      grants = visible_grants
+      grants = grants.for_connector(params[:type]) if params[:type].present?
+      include_data = params[:include_data].to_s == "true"
+
+      render json: { credentials: grants.order(updated_at: :desc).map { |g| serialize(g, include_data: include_data) } }
+    end
+
+    # GET /connectors/credentials/for-workflow
+    def for_workflow
+      grants = visible_grants
+      grants = grants.for_connector(params[:type]) if params[:type].present?
+      render json: { credentials: grants.order(updated_at: :desc).map { |g| serialize(g) } }
+    end
+
+    # GET /connectors/credentials/:id
+    def show
+      grant = find_visible_grant!(params[:id])
+      render json: serialize(grant, include_data: params[:include_data].to_s == "true")
+    end
+
+    # POST /connectors/credentials
+    # Body: { type, name, data?, external_ref?, is_managed? }
+    #
+    # When `is_managed: true` is passed (typically alongside `external_ref:
+    # "vault/path/foo"`), the DB only stores the reference + non-sensitive
+    # field defaults; the actual credential values come from the host's
+    # `secrets_resolver` at request time. n8n parity: external-secrets EE
+    # module (external-secrets.controller.ee.ts).
+    def create
+      owner = current_owner!
+      type  = params.fetch(:type)
+      klass = Registry.fetch(type)   # raises UnknownConnector → 404 if bogus
+
+      is_managed = [ true, "true", "1", 1 ].include?(params[:is_managed])
+      if is_managed && klass.skip_managed_creation?
+        raise Connectors::Error.new("managed credentials are disabled for #{type.inspect}")
+      end
+
+      data = (params[:data] || ActionController::Parameters.new).to_unsafe_h
+      data = MCP::ConnectionConfig.resolve(data, connector: klass, require_secrets: !is_managed) if klass.mcp?
+      grant = Grant.create!(
+        owner:         owner,
+        connector_key: type.to_s,
+        display_name:  params[:name].presence,
+        credentials:   data,
+        external_ref:  params[:external_ref].presence,
+        is_managed:    is_managed,
+        status:        :active,
+        last_used_at:  Time.current
+      )
+      render json: serialize(grant), status: :created
+    end
+
+    # GET /connectors/credentials/new?type=resend
+    # Server-generated unique default name ("Resend account 3"). n8n parity:
+    # `credentials.controller.ts:100-111`. The frontend pre-fills the name
+    # field with the response so the user can rename or accept the default.
+    def new
+      current_owner!
+      type = params.fetch(:type)
+      klass = Registry.fetch(type)
+      base  = klass.display_name || type.to_s.humanize
+      base += " account"
+
+      taken = Grant.where(connector_key: type.to_s)
+                   .where("display_name LIKE ?", "#{base}%")
+                   .pluck(:display_name)
+                   .compact
+      n = 1
+      n += 1 while taken.include?("#{base} #{n}")
+      render json: { name: "#{base} #{n}" }
+    end
+
+    # PATCH /connectors/credentials/:id
+    # Body: { name?, data? }   — data is merged into existing credentials.
+    # Requires `editor` (or owner) role.
+    def update
+      grant = find_visible_grant!(params[:id], min_role: :editor)
+
+      if params.key?(:data)
+        new_data = (params[:data] || {}).to_unsafe_h
+        klass = Registry.fetch(grant.connector_key)
+        if klass.mcp?
+          require_grant_role!(grant, :owner)
+          MCP::ConnectionConfig.resolve(grant.credentials_hash.except("mcp_oauth").merge(new_data), connector: klass)
+          new_data["mcp_oauth"] = nil
+        end
+        grant.update_credentials!(new_data)
+      end
+      grant.display_name = params[:name] if params.key?(:name)
+      grant.save! if grant.changed?
+
+      render json: serialize(grant)
+    end
+
+    # DELETE /connectors/credentials/:id — owner only.
+    def destroy
+      find_visible_grant!(params[:id], min_role: :owner).destroy
+      head :no_content
+    end
+
+    # PUT /connectors/credentials/:id/share
+    # Body: { principal_type: "User"|"Team"|..., principal_id: <uuid>, role: "viewer"|"editor" }
+    # Owner only. Adds (or updates) a share row.
+    def share
+      grant = find_visible_grant!(params[:id], min_role: :owner)
+      share = CredentialShare.find_or_initialize_by(
+        grant:          grant,
+        principal_type: params.fetch(:principal_type),
+        principal_id:   params.fetch(:principal_id).to_s
+      )
+      share.role = params.fetch(:role, "viewer")
+      share.save!
+      render json: serialize_share(share)
+    end
+
+    # DELETE /connectors/credentials/:id/share
+    # Body: { principal_type, principal_id: <uuid> }
+    def unshare
+      grant = find_visible_grant!(params[:id], min_role: :owner)
+      share = grant.shares.find_by!(
+        principal_type: params.fetch(:principal_type),
+        principal_id:   params.fetch(:principal_id).to_s
+      )
+      share.destroy
+      head :no_content
+    end
+
+    # PUT /connectors/credentials/:id/transfer
+    # Body: { owner_id: <uuid> } — moves ownership to a different owner.
+    # n8n parity: enterprise/credentials.controller.ee.ts transfer endpoint.
+    def transfer
+      grant         = find_visible_grant!(params[:id], min_role: :owner)
+      new_owner_klass = Connectors.configuration.owner_class_name.constantize
+      new_owner       = new_owner_klass.find(params.fetch(:owner_id).to_s)
+      grant.update!(owner: new_owner)
+      render json: serialize(grant)
+    end
+
+    # POST /connectors/credentials/test
+    # Test an UNSAVED credential. Body: { type, data: {...} }
+    # Spins up a transient Grant (not persisted) and runs the connector's
+    # declared test_request through it.
+    def test_unsaved
+      type = params.fetch(:type)
+      data = (params[:data] || {}).to_unsafe_h
+
+      transient = Grant.new(
+        owner:         current_owner!,
+        connector_key: type.to_s,
+        credentials:   data,
+        status:        :active
+      )
+      # Bypass save — we just need #connector and #credentials_hash.
+      transient.define_singleton_method(:credentials_hash) { credentials || {} }
+
+      result      = Connectors::CredentialTester.run(transient)
+      status_code = result[:status] == Connectors::CredentialTester::OK ? :ok : :unprocessable_content
+      render json: result, status: status_code
+    end
+
+    private
+
+    def serialize_share(share)
+      {
+        id:             share.id,
+        grant_id:       share.grant_id,
+        principal_type: share.principal_type,
+        principal_id:   share.principal_id,
+        role:           share.role
+      }
+    end
+
+    def serialize(grant, include_data: false)
+      h = {
+        id:                  grant.id,
+        type:                grant.connector_key,                       # n8n name
+        connector_key:       grant.connector_key,                       # @deprecated alias
+        name:                grant.display_name || "#{grant.connector_key} ##{grant.id}",
+        external_account_id: grant.external_account_id,
+        status:              grant.status,
+        expires_at:          grant.expires_at,
+        last_used_at:        grant.last_used_at,
+        created_at:          grant.created_at,
+        updated_at:          grant.updated_at,
+        scopes:              extract_scopes(grant),
+        # Phase 10 — external secrets manager. `is_managed: true` means the
+        # actual credential values are vault-sourced; `external_ref` is the
+        # opaque key the host's `secrets_resolver` uses to look them up.
+        is_managed:          grant.is_managed,
+        external_ref:        grant.external_ref,
+        # n8n's `__overwrittenProperties` (interfaces.ts:382) but per-grant
+        # so the editor can show "this field comes from Vault: <api_key>".
+        __overwritten_properties: grant.is_managed ? Connectors.configuration.managed_fields_for(grant.connector_key) : []
+      }
+      if include_data
+        if Registry.fetch(grant.connector_key).mcp?
+          h[:data] = MCP::ConnectionConfig.public_data(grant.credentials_hash)
+        elsif role_for(grant, owner: current_owner!) == "owner"
+          h[:data] = grant.credentials_hash
+        end
+      end
+      h
+    end
+
+    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_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