connectors 0.1.0

data/app/models/connectors/credential_share.rb

@@ -0,0 +1,31 @@
+module Connectors
+  # One sharing entry per (grant, principal) pair. The engine intentionally
+  # doesn't know what a principal is — `principal_type` / `principal_id`
+  # are opaque tuples supplied by the host's
+  # `Connectors.configuration.principal_resolver` block.
+  #
+  # `role` mirrors n8n's enterprise model: viewer = read-only, editor =
+  # update + use, owner = full control (delete + share + transfer). Only
+  # one `:owner` per grant — enforced by the unique index on
+  # `(grant_id, principal_type, principal_id)` plus a custom uniqueness
+  # validation per role.
+  class CredentialShare < ApplicationRecord
+    self.table_name = "connectors_credential_shares"
+
+    belongs_to :grant, class_name: "Connectors::Grant"
+
+    ROLES = %w[viewer editor owner].freeze
+    validates :role, inclusion: { in: ROLES }
+    validates :principal_type, :principal_id, presence: true
+    validates :principal_id, uniqueness: { scope: %i[grant_id principal_type] }
+
+    # `principals` is an array of [type, id] tuples, as returned by the
+    # host's `principal_resolver`. Returns shares matching ANY of them.
+    scope :for_principals, ->(principals) {
+      next none if principals.blank?
+      clause = principals.map { "(principal_type = ? AND principal_id = ?)" }.join(" OR ")
+      args   = principals.flat_map { |type, id| [ type.to_s, id ] }
+      where(clause, *args)
+    }
+  end
+end

data/app/models/connectors/grant.rb

@@ -0,0 +1,103 @@
+module Connectors
+  # A Grant is the user-authorized link between an owner (User, Workspace, etc.)
+  # and a third-party service. It stores the encrypted tokens / API keys needed
+  # to call that service's API on the owner's behalf.
+  class Grant < ApplicationRecord
+    serialize :credentials, coder: JSON, type: Hash
+    encrypts  :credentials
+
+    belongs_to :owner, polymorphic: true
+    has_many   :shares,         class_name: "Connectors::CredentialShare", dependent: :destroy
+    has_many   :webhook_events, class_name: "Connectors::WebhookEvent",    dependent: :destroy
+    has_many   :poll_states,    class_name: "Connectors::PollState",       dependent: :destroy
+
+    enum :status, { active: 0, expired: 1, revoked: 2, errored: 3 }, default: :active
+
+    validates :connector_key, presence: true
+
+    scope :for_connector, ->(key) { where(connector_key: key.to_s) }
+    scope :expiring_within, ->(window) { where(expires_at: ..window.from_now).where.not(expires_at: nil) }
+
+    # Returns an instance of the connector class registered for this grant's key.
+    def connector
+      Connectors::Registry.fetch(connector_key).new(self)
+    end
+
+    # Cached clients must observe revocation by another worker. Read only the
+    # status so pending changes to credentials or polling state are preserved.
+    def ensure_not_revoked!
+      revoked_in_database = persisted? && self.class.uncached { self.class.where(id: id, status: :revoked).exists? }
+      raise Connectors::AuthenticationFailed, "connection has been revoked" if revoked? || revoked_in_database
+    end
+
+    # Atomic merge into the encrypted credentials hash. Always go through this
+    # instead of mutating the hash in-place, since serialized columns don't
+    # dirty-track mutation. Invalidates the per-instance resolved cache so a
+    # follow-up `credentials_hash` re-blends the vault values.
+    def update_credentials!(patch)
+      patch = patch.stringify_keys
+      with_persistence_lock do
+        attrs = { credentials: (credentials || {}).merge(patch) }
+        attrs[:expires_at] = patch["expires_at"] && Time.at(patch["expires_at"].to_i) if patch.key?("expires_at")
+        update!(attrs)
+        clear_resolved_credentials
+      end
+    end
+
+    def reload(...)
+      clear_resolved_credentials
+      super
+    end
+
+    # Unsaved candidates can use the same primitives without attempting a row
+    # lock. Persisted grants always re-read under a database lock.
+    def with_persistence_lock(&block)
+      persisted? ? with_lock(&block) : yield
+    end
+
+    # Convenience accessor that always returns a hash, never nil. When the
+    # grant is `is_managed?`, the host's `secrets_resolver` is invoked and
+    # its return value is merged over the DB-stored credentials — the vault
+    # wins, so rotating a value in Vault propagates without a DB write.
+    # Cached per-instance to keep one request = one vault lookup.
+    def credentials_hash
+      return @resolved_credentials_hash if defined?(@resolved_credentials_hash)
+      base = credentials || {}
+      @resolved_credentials_hash = is_managed? ? base.merge(Connectors.configuration.resolve_secrets(self)) : base
+    end
+
+    # The raw, DB-only credentials hash (never consults the vault). Used by
+    # the index serializer to compute `__overwritten_properties` without
+    # tripping the resolver on every list response.
+    def stored_credentials_hash
+      credentials || {}
+    end
+
+    # Mirrors n8n's `getWorkflowStaticData('node')` — a small scratch hash
+    # the connector mutates between webhook lifecycle calls (or polling
+    # cursors). Save with `save!` after mutation, or use
+    # `update_static_data!(group, &block)` for the atomic path.
+    def static_data_hash
+      static_data || {}
+    end
+
+    # Yields the sub-hash for a webhook/polling group, then persists any
+    # mutation in a single UPDATE. Group defaults to "default" so single-
+    # webhook providers don't need to think about it.
+    def update_static_data!(group = "default")
+      with_persistence_lock do
+        data = static_data_hash.deep_dup
+        sub = (data[group.to_s] ||= {})
+        result = yield(sub)
+        update!(static_data: data)
+        result
+      end
+    end
+
+    private
+
+    def clear_resolved_credentials
+      remove_instance_variable(:@resolved_credentials_hash) if defined?(@resolved_credentials_hash)
+    end
+  end
+end

data/app/models/connectors/mcp_authorization.rb

@@ -0,0 +1,6 @@
+module Connectors
+  class McpAuthorization < ApplicationRecord
+    REQUIRED_ROLE = :owner
+    include MCP::PendingTransaction
+  end
+end

data/app/models/connectors/mcp_interaction.rb

@@ -0,0 +1,6 @@
+module Connectors
+  class McpInteraction < ApplicationRecord
+    REQUIRED_ROLE = :editor
+    include MCP::PendingTransaction
+  end
+end

data/app/models/connectors/poll_state.rb

@@ -0,0 +1,17 @@
+module Connectors
+  # One cursor/configuration per consumer of a connection. instance_key is an
+  # opaque identifier supplied by the host (for example its trigger ID).
+  class PollState < ApplicationRecord
+    belongs_to :grant, class_name: "Connectors::Grant"
+    validates :instance_key, presence: true
+
+    def update_cursor!
+      with_lock do
+        cursor = data.deep_dup
+        result = yield(cursor)
+        update!(data: cursor)
+        result
+      end
+    end
+  end
+end

data/app/models/connectors/webhook_event.rb

@@ -0,0 +1,19 @@
+module Connectors
+  # One record per inbound webhook from a provider. Persisted before
+  # processing so handlers can crash without losing the event, and so the
+  # idempotency index (connector_key, external_event_id) drops duplicates.
+  class WebhookEvent < ApplicationRecord
+    belongs_to :grant, class_name: "Connectors::Grant"
+
+    enum :status, { received: 0, processed: 1, failed: 2, ignored: 3 }, default: :received
+
+    validates :connector_key, :received_at, presence: true
+
+    scope :for_connector, ->(key) { where(connector_key: key.to_s) }
+    scope :unprocessed,   -> { where(status: %i[received failed]) }
+
+    def payload_hash
+      payload || {}
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,68 @@
+Connectors::Engine.routes.draw do
+  get  "/credentials/:id/mcp/tools", to: "mcp#tools"
+  post "/credentials/:id/mcp/tools/call", to: "mcp#call_tool"
+  post "/credentials/:id/mcp/interactions/resume", to: "mcp#resume"
+  post "/credentials/:id/mcp/authorize", to: "mcp#authorize"
+  get  "/mcp/oauth/callback", to: "mcp#callback"
+  post "/mcp/oauth/callback", to: "mcp#callback"
+  # Catalog + connected-account introspection. Declared first so /grants and
+  # /types aren't interpreted as a :connector_key.
+  # n8n-shape credential CRUD (the canonical endpoints — frontend uses these).
+  get    "/credentials",                    to: "credentials#index",        as: :credentials
+  get    "/credentials/for-workflow",       to: "credentials#for_workflow", as: :credentials_for_workflow
+  post   "/credentials/test",               to: "credentials#test_unsaved", as: :test_unsaved_credential
+  get    "/credentials/new",                to: "credentials#new",          as: :new_credential
+  post   "/credentials",                    to: "credentials#create"
+  get    "/credentials/:id",                to: "credentials#show",         as: :credential
+  patch  "/credentials/:id",                to: "credentials#update"
+  put    "/credentials/:id",                to: "credentials#update"
+  delete "/credentials/:id",                to: "credentials#destroy"
+  post   "/credentials/:id/revoke",         to: "oauth#revoke",             as: :revoke_credential
+
+  # Action manifest + invocation. Per-credential because actions need an
+  # authenticated grant to run against; the catalog at /types/:name also
+  # includes a static `actions: [...]` array for design-time browsing.
+  get    "/credentials/:id/actions",        to: "actions#index",            as: :credential_actions
+  post   "/credentials/:id/actions/:name",  to: "actions#create",           as: :invoke_credential_action,
+                                            constraints: { name: /[^\/]+/ }
+
+  # Phase 9 — credential sharing / scoping
+  put    "/credentials/:id/share",          to: "credentials#share",        as: :share_credential
+  delete "/credentials/:id/share",          to: "credentials#unshare"
+  put    "/credentials/:id/transfer",       to: "credentials#transfer",     as: :transfer_credential
+
+  # @deprecated `/grants` aliases — keep working until the frontend migrates.
+  get  "/grants",                           to: "grants#index",     as: :grants
+  post "/grants/:id/test",                  to: "grants#test",      as: :test_grant
+  post   "/grants/:id/webhook_subscribe",   to: "grants#webhook_subscribe",   as: :webhook_subscribe_grant
+  delete "/grants/:id/webhook_subscribe",   to: "grants#webhook_unsubscribe"
+  post   "/grants/:id/poll",                to: "grants#poll",                as: :poll_grant
+  get  "/types",                            to: "types#index",      as: :types
+  get  "/types/:name",                      to: "types#show",       as: :type, constraints: { name: /[^\/]+/ }
+
+  # Split frontend/backend OAuth completion (Activepieces-style). The
+  # frontend's `/oauth/callback` page POSTs `{code, state}` here after the
+  # provider redirects to it.
+  post "/oauth/exchange",                   to: "oauth#exchange",       as: :oauth_exchange
+
+  get  "/:connector_key/authorize.json",    to: "oauth#authorize_json", as: :authorize_json
+  get  "/:connector_key/authorize",         to: "oauth#authorize",      as: :authorize
+  # Legacy monolithic-host callback — same-origin frontend/backend hosts
+  # (n8n-style). Split-origin apps point the redirect_uri at the frontend
+  # and POST to /oauth/exchange instead.
+  get  "/:connector_key/callback",          to: "oauth#callback",       as: :callback
+
+  # App-level webhook URL (Slack, GitHub Apps, Linear, Notion, ...): one URL
+  # per app, grant resolved from payload via Connector.resolve_grant_from_webhook.
+  post "/:connector_key/webhook",                          to: "webhooks#receive", as: :app_webhook
+
+  # Phase 7 — multi-webhook providers route by `webhook_name` segment so
+  # `webhookMethods.default` and `webhookMethods.setup` get distinct URLs
+  # (mirrors n8n's `IWebhookDescription.name` at interfaces.ts:2600).
+  post "/:connector_key/webhook/:webhook_name",            to: "webhooks#receive", as: :named_app_webhook
+
+  # Per-grant webhook URL (Stripe, Twilio, ...): grant explicit in URL.
+  # Must be declared AFTER /webhook so the bare form isn't shadowed.
+  post "/:connector_key/:grant_id/webhook",                to: "webhooks#receive", as: :webhook
+  post "/:connector_key/:grant_id/webhook/:webhook_name",  to: "webhooks#receive", as: :named_webhook
+end

data/db/migrate/20260518210324_create_connectors_grants.rb

@@ -0,0 +1,49 @@
+class CreateConnectorsGrants < ActiveRecord::Migration[8.1]
+  def change
+    # Everything is uuid — engine-owned primary keys AND polymorphic owner
+    # columns. The host (and any other owner type — Team, Workspace, …) is
+    # expected to have uuid PKs too. `gen_random_uuid()` is a PG13+ built-in,
+    # no extension required.
+    create_table :connectors_grants, id: :uuid do |t|
+      t.references :owner, polymorphic: true, type: :uuid, null: false
+      t.string   :connector_key,       null: false
+      t.string   :display_name
+      t.text     :credentials                       # encrypted at rest via ActiveRecord::Encryption
+      t.integer  :status,              null: false, default: 0
+      t.datetime :expires_at
+      t.datetime :last_used_at
+      t.string   :external_account_id               # provider-side user/account id, if applicable
+
+      # Per-grant scratch storage for webhook subscriptions + polling cursors
+      # (n8n parity: `getWorkflowStaticData('node')` at interfaces.ts:1257-1274).
+      # Each `webhook_methods` group writes into its own nested hash keyed
+      # by the group name, so multi-webhook providers can persist
+      # independent state per subscription type.
+      t.jsonb    :static_data,         null: false, default: {}
+
+      # External secrets manager integration. A grant either stores its
+      # credentials inline (DB-encrypted) OR carries a lightweight
+      # `external_ref` that the host's vault adapter resolves on demand.
+      # n8n parity: `__overwrittenProperties` on the credential type
+      # (interfaces.ts:382), populated by frontend.service.ts:681-705
+      # when the external-secrets EE module is active.
+      t.string   :external_ref
+      t.boolean  :is_managed,          null: false, default: false
+
+      t.timestamps
+    end
+
+    add_index :connectors_grants,
+              [ :owner_type, :owner_id, :connector_key ],
+              name: "index_connectors_grants_on_owner_and_connector"
+
+    add_index :connectors_grants, :connector_key
+    add_index :connectors_grants, :expires_at
+    add_index :connectors_grants, :status
+    add_index :connectors_grants,
+              [ :connector_key, :external_account_id ],
+              where: "external_account_id IS NOT NULL",
+              name: "index_connectors_grants_on_external_account"
+    add_index :connectors_grants, :external_ref, where: "external_ref IS NOT NULL"
+  end
+end

data/db/migrate/20260518214609_create_connectors_webhook_events.rb

@@ -0,0 +1,35 @@
+class CreateConnectorsWebhookEvents < ActiveRecord::Migration[8.1]
+  def change
+    create_table :connectors_webhook_events, id: :uuid do |t|
+      t.references :grant, type: :uuid, null: false, foreign_key: { to_table: :connectors_grants }
+      t.string   :connector_key,     null: false
+      t.string   :external_event_id
+      t.jsonb    :payload
+      t.text     :signature
+      t.integer  :status,            null: false, default: 0
+      t.text     :error_message
+      t.datetime :received_at,       null: false
+      t.datetime :processed_at
+
+      # Full inbound request shape so `IWebhookFunctions`-style handlers
+      # have headers (Stripe-Signature etc.), query string, raw body (for
+      # replay / signature debugging), and the named webhook group the
+      # request hit (`webhookMethods.default` vs `.setup`).
+      t.jsonb    :headers,      null: false, default: {}
+      t.jsonb    :query,        null: false, default: {}
+      t.text     :raw_body
+      t.string   :webhook_name, null: false, default: "default"
+
+      t.timestamps
+    end
+
+    add_index :connectors_webhook_events, :connector_key
+    add_index :connectors_webhook_events, :status
+    add_index :connectors_webhook_events, :webhook_name
+    add_index :connectors_webhook_events,
+              [ :connector_key, :external_event_id ],
+              unique: true,
+              where:  "external_event_id IS NOT NULL",
+              name:   "idx_connectors_webhook_events_idempotency"
+  end
+end

data/db/migrate/20260521140000_create_connectors_credential_shares.rb

@@ -0,0 +1,26 @@
+class CreateConnectorsCredentialShares < ActiveRecord::Migration[8.1]
+  # Phase 9 — credential sharing. One row per (grant, principal) pair.
+  # `principal_type` is whatever the host wires through the
+  # `Connectors.configuration.principal_resolver` block — it's almost
+  # always "User" but EE hosts may share to "Team" / "Project" / etc.
+  #
+  # n8n parity: enterprise/credentials.controller.ee.ts handles
+  # `PUT /credentials/:id/share` + `/transfer`. We give the engine the
+  # SAME storage shape without baking in host-app concepts.
+  def change
+    create_table :connectors_credential_shares, id: :uuid do |t|
+      t.references :grant, type: :uuid, null: false, foreign_key: { to_table: :connectors_grants }
+      t.string     :principal_type, null: false
+      t.uuid       :principal_id,   null: false
+      t.string     :role,           null: false, default: "viewer"
+
+      t.timestamps
+    end
+
+    add_index :connectors_credential_shares, [ :grant_id, :principal_type, :principal_id ],
+              unique: true,
+              name:   "idx_connectors_credential_shares_uniq"
+    add_index :connectors_credential_shares, [ :principal_type, :principal_id ],
+              name: "idx_connectors_credential_shares_lookup"
+  end
+end

data/db/migrate/20260922120000_create_connectors_poll_states.rb

@@ -0,0 +1,12 @@
+class CreateConnectorsPollStates < ActiveRecord::Migration[8.1]
+  def change
+    create_table :connectors_poll_states, id: :uuid do |t|
+      t.references :grant, type: :uuid, null: false, foreign_key: { to_table: :connectors_grants }
+      t.string :instance_key, null: false
+      t.jsonb :data, null: false, default: {}
+      t.timestamps
+    end
+
+    add_index :connectors_poll_states, [ :grant_id, :instance_key ], unique: true
+  end
+end

data/db/migrate/20260922130000_create_connectors_mcp_transactions.rb

@@ -0,0 +1,18 @@
+class CreateConnectorsMcpTransactions < ActiveRecord::Migration[8.1]
+  def change
+    %i[mcp_authorizations mcp_interactions].each do |name|
+      create_table "connectors_#{name}", id: :uuid do |t|
+        t.references :grant, type: :uuid, null: false, foreign_key: { to_table: :connectors_grants, on_delete: :cascade }
+        t.string :actor_key, null: false
+        t.string :fingerprint, null: false
+        t.string :status, null: false, default: "pending"
+        t.text :payload, null: false
+        t.datetime :expires_at, null: false
+        t.timestamps
+      end
+      add_index "connectors_#{name}", :expires_at
+    end
+    add_column :connectors_mcp_authorizations, :state_digest, :string, null: false
+    add_index :connectors_mcp_authorizations, :state_digest, unique: true
+  end
+end

data/docs/adding-connectors.md

@@ -0,0 +1,92 @@
+# Adding a connector
+
+Use a REST connector when the backend should implement provider actions against an HTTP API. Use an MCP profile when the provider exposes a compatible remote MCP server and supplies its own tool schemas. See [architecture](architecture.md) for the separation.
+
+## REST connector
+
+Choose a unique key and place the class in the host's `app/connectors/<key>/connector.rb`. Match the Ruby namespace to the directory for Zeitwerk. The example below is a fictional CRM template, not a claim about an existing provider API:
+
+```ruby
+# app/connectors/example_crm/connector.rb
+module ExampleCrm
+  class Connector < Connectors::Connector
+    connector key: :example_crm, auth: :api_key,
+      base_url: "https://api.example.test", display_name: "Example CRM"
+
+    credentials do
+      field :api_key, type: "string", required: true, secret: true
+    end
+
+    authenticate type: :generic, properties: {
+      headers: { "Authorization" => "=Bearer {{$credentials.api_key}}" }
+    }
+
+    test_request method: :get, url: "me"
+
+    action :find_contact, display_name: "Find Contact" do
+      field :email, type: "string", required: true
+      execute do |input|
+        client.get("contacts", { email: input.fetch("email") }).body
+      end
+    end
+  end
+end
+```
+
+Replace the endpoint, authentication and action with the provider's documented contract. Use the shared `client` for request timeouts, authentication, revocation, retries and error handling. Do not store real keys in connector classes. Set safe fixed provider URLs; do not turn untrusted action inputs into arbitrary destinations.
+
+`test_request` should use a cheap, read-only endpoint compatible with the credential's permissions. A successful test establishes access to that endpoint, not every possible action. Document scope restrictions.
+
+REST actions check required values and remove undeclared keys. Add provider-specific validation when required; field types primarily describe the UI. OAuth2/OAuth1, pre-authentication, webhooks, polling and credential inheritance are documented in the [DSL reference](../CONNECTORS_FRAMEWORK.md). Declare only capabilities you actually implement.
+
+## Test first
+
+In the gem repository, use `rails_helper` for the dummy application, registry reset and WebMock. In a host project, configure equivalent owner, encryption and database fixtures. With the example connector loaded:
+
+```ruby
+require "rails_helper"
+
+RSpec.describe ExampleCrm::Connector do
+  let(:owner) { Owner.create!(name: "CRM test") }
+  let(:grant) do
+    Connectors::Grant.create!(owner: owner, connector_key: "example_crm",
+      credentials: { "api_key" => "synthetic-key" })
+  end
+
+  it "finds contacts through the authenticated client" do
+    stub_request(:get, "https://api.example.test/contacts")
+      .with(query: { email: "person@example.test" },
+        headers: { "Authorization" => "Bearer synthetic-key" })
+      .to_return(status: 200, headers: { "Content-Type" => "application/json" },
+        body: '{"contacts":[]}')
+
+    result = Connectors::ActionRunner.call(grant, :find_contact,
+      { "email" => "person@example.test" })
+    expect(result[:status]).to eq("ok")
+    expect(result[:data]).to eq("contacts" => [])
+  end
+end
+```
+
+Add cases for the provider's documented errors, scope restrictions and required input; verify write operations are not replayed unexpectedly. For webhooks test signature validation, grant routing and duplicate events. For polling test cursor isolation and rollback on failure. Avoid tests that only repeat DSL declarations without verifying behavior.
+
+## Named MCP profile
+
+For a server supported by the generic MCP integration, a named profile supplies fixed connection metadata. It does not copy remote tools into Ruby action classes:
+
+```ruby
+# app/connectors/example_mcp/connector.rb
+module ExampleMcp
+  class Connector < Connectors::Connector
+    connector key: :example_mcp, auth: :api_key, base_url: nil,
+      display_name: "Example MCP"
+    mcp server_url: "https://mcp.example.test/mcp", auth_mode: "oauth"
+  end
+end
+```
+
+The `auth: :api_key` field is the current base connector DSL marker; the `mcp` declaration selects OAuth for the remote connection. It does not enable an API-key fallback. For servers needing preregistered clients, declare the optional secret `client_information` credential field as the shipped ClickUp profile does.
+
+Confirm the actual server's transport/protocol support, endpoint, OAuth discovery metadata, scopes and client registration requirements using official documentation and live read-only metadata. Do not assume all servers support dynamic registration, refresh tokens or the same scopes. Test fixed-profile configuration, consent requirements, sanitized credential responses, discovery and invocation. Use the shared MCP services; add no provider-specific token logic unless the actual contract requires it.
+
+See [ClickUp](../MCP_CLIENT.md#clickup) for the implemented example and [contributing](../CONTRIBUTING.md) for full verification commands.

data/docs/architecture.md

@@ -0,0 +1,71 @@
+# Architecture and execution contracts
+
+Connectors is a Rails engine. It does not provide a workflow executor, account login UI, scheduler or hosted provider proxy. The [README](../README.md) describes installation; the [framework reference](../CONNECTORS_FRAMEWORK.md) describes the DSL.
+
+## Components
+
+| Component | Responsibility |
+| --- | --- |
+| Host application | Authenticated owner/principals, encryption keys, provider application secrets, job backend, scheduling and business workflows |
+| Registry and connector classes | Credential schemas, provider metadata, REST actions, authentication declarations and optional polling/webhooks |
+| `Connectors::Grant` | One connected account; encrypted credentials, status, ownership and provider identity |
+| Credential shares | Grant access for UUID principals with viewer, editor or owner roles |
+| REST execution | Declared actions and Faraday middleware for credential injection, refresh, errors and retries |
+| MCP client | Grant-scoped remote discovery, schema validation, transport, OAuth and durable interactions |
+| Controllers | HTTP access checks and stable request/response envelopes |
+
+Classes under `app/connectors/*/connector.rb` register through the connector DSL when Rails loads them. The engine's `to_prepare` hook loads shipped and host connector classes. Remote MCP tools are discovered for each authorized grant; they do not become global connector classes.
+
+## REST actions
+
+```text
+Authenticated app request
+  → engine role check (editor or owner)
+  → declared action lookup and revocation check
+  → required-parameter validation and input whitelist
+  → provider action implementation
+  → Faraday: rate limit / refresh / error normalization / retries
+  → per-attempt revocation check / pre-authentication / credential injection
+  → provider
+  → normalized action result
+```
+
+`ActionRunner.call(grant, name, input)` is also available to trusted host code. It checks revocation, but it does not accept an actor or perform sharing authorization: the host must authorize the selected grant before calling it. Connector methods using `client` get the same HTTP checks. Provider implementations that bypass `client` also bypass that middleware.
+
+Action field declarations describe the form and required values; they are not a general JSON Schema validator. Unknown REST action keys are dropped. Provider actions must validate constraints beyond required values where needed.
+
+## MCP tools
+
+```text
+Authenticated app request
+  → MCP access check for the grant and actor
+  → discover provider tool descriptors
+  → validate arguments against the selected tool's schema
+  → transport with grant credentials and protocol metadata
+  → provider tools/call
+  → native tool result, or persisted input_required interaction
+```
+
+The backend handles discovery, registration, OAuth scopes and token use. The frontend renders tool input and explicit user consent/elicitation; it does not implement provider authentication or requests. Unlike the REST Ruby runner, `MCP::Client.new(grant:, actor:, principals:)` checks access itself. HTTP tools and actions currently have separate endpoints.
+
+OAuth and elicitation use encrypted, expiring database records bound to the actor, grant and connection fingerprint. One-time transaction claims prevent local replay. They do not guarantee exactly-once execution at the remote provider. A network interruption can leave a remote operation's outcome unknown. See [MCP support and limits](../MCP_CLIENT.md).
+
+## Persistence and encryption
+
+Credentials and MCP transaction payloads use Rails Active Record Encryption. Owner IDs, connection metadata, polling state and webhook bodies are not all encrypted by this feature. Webhook raw bodies/payloads and polling state can contain provider data; hosts must apply their own retention and access rules.
+
+Credential merges and OAuth refresh coordinate with row locks. Polling can keep one cursor per `(grant, instance_key)`, so independent consumers do not share progress accidentally. Revocation checks query current persisted status to handle cached clients; in-flight network requests cannot be recalled.
+
+## Webhooks and polling
+
+Inbound webhook handling resolves the connector and grant, applies that connector's verification, persists a `WebhookEvent` and queues delivery. `DeliverWebhookJob` invokes the connector handler and optional host hook. Deduplication uses provider event IDs when available. Verification and extraction rules are provider-specific.
+
+The host activates/deactivates declared webhook subscriptions and schedules polling. Polling commits cursor changes after a successful provider call; reliable delivery of returned items to downstream workflows is a host concern. No engine process runs an autonomous schedule.
+
+## Errors and operational limits
+
+REST actions return typed error envelopes; the HTTP layer maps validation, authentication, permission and quota failures to appropriate statuses. Other provider action failures use 502. Direct Ruby clients raise library errors where no action envelope is involved.
+
+MCP preserves tool-level `isError` results separately from HTTP/protocol errors. Upstream HTTP 429 returns `rate_limited` with valid optional retry guidance. MCP transport bounds request duration, body size, pagination and interaction rounds; it validates and pins destinations. See the MCP guide for exact defaults and supported authentication mechanisms.
+
+Production acceptance requires verification in the intended host and provider account. Passing package checks demonstrates that consumers can load the distributed artifact; it does not establish provider uptime, sufficient scopes, application authorization or load capacity.

data/docs/releasing.md

@@ -0,0 +1,60 @@
+# Releasing Connectors
+
+The public source repository is [jackhelio/connectors](https://github.com/jackhelio/connectors). The gemspec permits publishing only to `https://rubygems.org`. Releases use GitHub Actions and RubyGems Trusted Publishing; no permanent RubyGems API token is stored in GitHub.
+
+## Account and repository setup
+
+Enable [multi-factor authentication](https://guides.rubygems.org/setting-up-multifactor-authentication/) on the maintainer's RubyGems account. Save recovery codes outside the repository.
+
+For the first release, create a [pending trusted publisher](https://rubygems.org/profile/oidc/pending_trusted_publishers):
+
+| Field | Value |
+| --- | --- |
+| Gem name | `connectors` |
+| Repository owner | `jackhelio` |
+| Repository | `connectors` |
+| Workflow filename | `release.yml` |
+| GitHub environment | `release` |
+
+Leave the optional workflow repository fields blank: publication runs directly in this repository's workflow. Pending publishers support the first upload and become regular trusted publishers after publication; an initial manual upload is unnecessary. Creating a pending publisher does not reserve a gem name. See the official [Trusted Publishing guide](https://guides.rubygems.org/trusted-publishing/).
+
+Create the matching GitHub environment `release`, with a deployment tag policy allowing `v*`. Keep `main` protected with the `lint` and `test` checks required. Only maintainers with repository write access should create release tags. The release job additionally checks that the tagged commit is on `main` and that the tag matches the gem version.
+
+## Verify a release candidate
+
+1. Update `lib/connectors/version.rb` and the lockfile when changing versions. Finalize the corresponding version's changelog and compatibility notes.
+2. Run the randomized RSpec suite and RuboCop against a disposable PostgreSQL database as described in [contributing](../CONTRIBUTING.md).
+3. Verify the distributable package:
+
+   ```sh
+   bundle exec ruby script/verify_package.rb
+   bundle exec gem build connectors.gemspec --strict
+   gem specification connectors-0.1.0.gem files
+   ```
+
+   Replace the artifact version when preparing a later release. The verification script checks public metadata, required files and documentation links, installs the gem into a temporary directory, and boots a fresh Rails host outside the checkout. It checks the shipped connector registry, migration discovery and MCP schema loading. It neither publishes nor invokes a provider. RSpec runs this same check in CI.
+
+4. Merge the reviewed release changes through a pull request after its required checks pass. Confirm CI on the merged `main` commit also passes.
+5. Confirm the RubyGems account and publisher configuration above are complete before pushing a tag.
+
+The package includes runtime code, migrations, protocol data/licenses and consumer documentation. Tests, the dummy host, development tooling, lockfile, workflows and ignored internal planning documents remain outside the gem. Develop from the source repository, not the installed package.
+
+## Publish the verified commit
+
+Fetch the merged commit, confirm its version and green CI, then create an annotated tag pointing to that exact commit:
+
+```sh
+git fetch origin --tags
+git tag -a v0.1.0 <verified-main-commit-sha> -m "Release 0.1.0"
+git push origin v0.1.0
+```
+
+Replace the SHA placeholder and version. Pushing the tag starts `.github/workflows/release.yml`. It reuses the normal CI workflow to run lint and the full RSpec suite before the publishing job starts. The publishing job verifies the tag, ancestry and package, builds the gem strictly, exchanges GitHub OIDC identity for short-lived RubyGems credentials using the official credentials action, then pushes the package. Only this job has `id-token: write`; neither job needs repository write permission.
+
+Watch the Release workflow and verify the version, metadata and artifact on [RubyGems](https://rubygems.org/gems/connectors). Install the published version into a clean host before announcing it. A successful test run alone is not proof of publication.
+
+If authentication fails before upload, fix the account/publisher configuration and rerun the workflow for the same tag. If upload may have succeeded, check RubyGems before retrying. Published versions cannot be overwritten; subsequent code changes require a new version and tag. Do not move a published release tag. Do not use `bundle exec rake release` as a validation command: it can tag, push and publish outside this workflow.
+
+## Supported baseline
+
+The gem declares Ruby 3.2+ and Rails 8.1.3+ within the 8.1 series. CI exercises Ruby 3.4.8 with PostgreSQL 16. Broader compatibility needs its own validation. Host authentication, encryption configuration, provider interoperability and production operations remain separate from package verification.