connectors 0.1.0 → 0.1.1

data/lib/connectors/engine.rb

@@ -32,11 +32,9 @@ module Connectors
     initializer :connectors_register_credential_types do
       reg = ::Connectors::CredentialTypeRegistry
       reg.register(:oauth2,           reg::OAUTH2)
-      # Phase 4 — n8n's `OAuth1Api` base type
-      # (packages/nodes-base/credentials/OAuth1Api.credentials.ts:1-72).
+      # Register the OAuth1 base credential schema.
       reg.register(:oauth1_api,       reg::OAUTH1)
-      # Phase 2 — n8n's generic HTTP auth credential types
-      # (packages/nodes-base/credentials/Http*Auth.credentials.ts).
+      # Register reusable HTTP authentication schemas.
       reg.register(:http_basic_auth,  ::Connectors::CredentialTypes::HTTP_BASIC_AUTH)
       reg.register(:http_bearer_auth, ::Connectors::CredentialTypes::HTTP_BEARER_AUTH)
       reg.register(:http_header_auth, ::Connectors::CredentialTypes::HTTP_HEADER_AUTH)
@@ -54,8 +52,7 @@ module Connectors
     #
     # Walks every Engine root (including the host's main app) and globs each
     # one's `app/connectors/` — the union covers shipped connectors here in
-    # the engine, plus host-app overrides under flow-api's own
-    # `app/connectors/` (if/when the host decides to ship its own).
+    # the engine and connectors defined in the host's app/connectors directory.
     config.to_prepare do
       ::Rails::Engine.subclasses.map(&:instance).push(::Rails.application).uniq.each do |engine|
         dir = engine.root.join("app/connectors")

data/lib/connectors/errors.rb

@@ -32,11 +32,8 @@ module Connectors
   class AuthenticationFailed < ApiError; end
   class Forbidden < ApiError; end
 
-  # A credential was used with a node that's not on its `supported_nodes`
-  # allowlist, OR the credential is marked generic_auth-only and the caller
-  # is a non-HTTP-Request node. Mirrors the visibility gate n8n applies via
-  # the credential's `supportedNodes` field (interfaces.ts:381) and
-  # `genericAuth` flag (interfaces.ts:379).
+  # Raised when a credential does not permit the requested node type
+  # under its supported_nodes and generic_auth settings.
   class CredentialNotPermitted < Error
     def initialize(connector_key, node_type, reason: nil)
       msg = "credential #{connector_key.inspect} is not permitted for node #{node_type.inspect}"

data/lib/connectors/middleware/authenticate_generic.rb

@@ -2,17 +2,9 @@ require "base64"
 
 module Connectors
   module Middleware
-    # Faraday middleware that applies a connector's declarative
-    # `authenticate type: :generic, properties: {...}` block to every
-    # outgoing request, mirroring n8n's `IAuthenticateGeneric` runtime
-    # (n8n source: packages/workflow/src/interfaces.ts:278-288 + the
-    # request-helpers consumer at
-    # packages/core/src/node-execute-functions.ts).
-    #
-    # The Grant's credentials hash supplies values for the
-    # `={{$credentials.x}}` templates inside `properties`. Resolution runs
-    # per-request so credentials that rotate between requests (e.g. after a
-    # `preAuthentication` hook lands in Phase 3) are reflected immediately.
+    # Apply resolved authentication properties to each outgoing request.
+    # Credential templates are evaluated per request so rotated values,
+    # including values from pre_authentication, take effect immediately.
     class AuthenticateGeneric < Faraday::Middleware
       def initialize(app, grant:, authenticate_config:)
         super(app)
@@ -63,9 +55,7 @@ module Connectors
         body.each { |k, v| env.body[k.to_s] = v }
       end
 
-      # n8n's `IRequestOptionsSimplifiedAuth.auth` shortcut for HTTP Basic
-      # (interfaces.ts:198-202). Sets the `Authorization: Basic ...` header
-      # directly so we don't double-handle.
+      # Set the HTTP Basic Authorization header from username and password.
       def apply_basic_auth(env, auth)
         return if auth.nil?
         username = auth[:username] || auth["username"]

data/lib/connectors/middleware/pre_authentication.rb

@@ -1,18 +1,7 @@
 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`.
+    # Run pre_authentication when expires_at is absent or in the past.
+    # Merge returned credentials before AuthenticateGeneric injects them.
     class PreAuthentication < Faraday::Middleware
       def initialize(app, grant:, pre_auth_block:)
         super(app)

data/lib/connectors/oauth/authorize_url.rb

@@ -16,11 +16,8 @@ module Connectors
         @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.
+      # The declared scopes are defaults; callers can override them
+      # per authorization request through the scope argument.
       def build(owner:, return_to: nil, scope: nil, name: nil, grant: nil)
         pkce = pkce_params if @config[:grant_type].to_s == "pkce"
 
@@ -66,10 +63,7 @@ module Connectors
         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).
+      # Use a configured frontend callback or the mounted engine callback.
       def redirect_uri
         Connectors.configuration.resolved_app_callback_url(@connector_class.connector_key)
       end

data/lib/connectors/oauth/client_credentials.rb

@@ -7,10 +7,6 @@ module Connectors
     # `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

data/lib/connectors/oauth/pkce.rb

@@ -4,15 +4,9 @@ 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.
+    # RFC 7636 PKCE using S256. Generate a random verifier and derive
+    # BASE64URL(SHA256(verifier)). Store the verifier in authenticated, encrypted
+    # OAuth state for use during the callback token exchange.
     module Pkce
       module_function
 

data/lib/connectors/oauth/revoke.rb

@@ -9,13 +9,9 @@ module Connectors
     # 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']}")
+    #   revoke_token do |grant|
+    #     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

data/lib/connectors/oauth1.rb

@@ -5,12 +5,8 @@ require "uri"
 require "faraday"
 
 module Connectors
-  # OAuth1.0a — RFC 5849. Two-leg request-token / access-token flow with
-  # HMAC-SHA1/SHA256/SHA512 request signing. n8n parity:
-  # `oauth.service.ts:601-700` (request-token leg) +
-  # `oauth1-credential.controller.ts:43-101` (callback / access-token leg).
-  # n8n uses the `oauth-1.0a` npm package; we implement the signing inline
-  # to keep the engine dependency-free.
+  # OAuth1.0a (RFC 5849) request-token and access-token exchanges
+  # with HMAC-SHA1, HMAC-SHA256 or HMAC-SHA512 signing.
   module OAuth1
     module_function
 
@@ -20,7 +16,7 @@ module Connectors
       "HMAC-SHA512" => "SHA512"
     }.freeze
 
-    # Phase 1 of the flow: request the unauthorized request token. Sends an
+    # Request-token step: request the unauthorized request token. Sends an
     # OAuth1-signed POST to `requestTokenUrl`. Provider returns
     # `oauth_token` + `oauth_token_secret` (URL-encoded form). We need both
     # to (a) build the authorize URL the owner is redirected to and (b)
@@ -60,7 +56,7 @@ module Connectors
       }
     end
 
-    # Phase 2: trade the verifier + token for the long-lived access token.
+    # Exchange the verifier and request token for an access token.
     def exchange_access_token(connector_class, oauth_token:, oauth_verifier:, oauth_token_secret:)
       config  = connector_class.oauth1_config or
         raise Connectors::Error.new("#{connector_class}: oauth1 ... DSL not declared")

data/lib/connectors/permission_check.rb

@@ -1,8 +1,6 @@
 module Connectors
-  # Visibility gate for credentials. Mirrors n8n's two-pronged check
-  # (interfaces.ts:379 + :381) — `genericAuth: true` lets the generic
-  # HTTP-Request node use any credential, and `supportedNodes: [...]`
-  # restricts a credential to a specific node allowlist when set.
+  # Enforce supported_nodes restrictions, including generic_auth permission
+  # for :http_request. An empty allowlist permits every node type.
   #
   # Call from inside a node's execution wrapper before it touches the grant:
   #

data/lib/connectors/poll_runner.rb

@@ -3,11 +3,7 @@ module Connectors
   # and filters even when consumers share credentials. Omitting the key keeps
   # the legacy, per-grant cursor for existing single-consumer integrations.
   #
-  # n8n parity: `INodeType#poll(this: IPollFunctions)` (interfaces.ts:2060),
-  # cursor persistence via `getWorkflowStaticData('node')`
-  # (interfaces.ts:1257-1274). The scheduler that decides *when* to fire
-  # this is a workflow-roadmap concern; this primitive just exposes the
-  # one-shot contract.
+  # The host schedules calls and delivers returned items.
   class PollRunner
     GROUP = "polling".freeze
 

data/lib/connectors/pre_authentication_helpers.rb

@@ -1,10 +1,6 @@
 module Connectors
-  # Helpers passed to a connector's `pre_authentication` block — mirrors
-  # n8n's `IHttpRequestHelper.helpers` surface (n8n source:
-  # packages/workflow/src/interfaces.ts:210-212). The block uses this to
-  # fetch a fresh token from an arbitrary endpoint without needing the
-  # full connector client (which itself depends on credentials that may
-  # not exist yet on first auth).
+  # HTTP helper for pre_authentication. Fetches credentials independently
+  # of the connector client, whose authentication may not yet be available.
   #
   #   pre_authentication do |credentials, helpers|
   #     response = helpers.http_request(
@@ -44,9 +40,8 @@ module Connectors
         req.body   = body  if body
       end
 
-      # Match n8n's `helpers.httpRequest` default: non-2xx becomes an error
-      # the pre_authentication hook can catch. Keeps "auth endpoint
-      # exploded" failures visible instead of silently merging a nil token.
+      # Raise on non-2xx responses so the hook cannot silently merge
+      # an unsuccessful token response into credentials.
       if response.status >= 400
         body_preview = response.body.is_a?(String) ? response.body.byteslice(0, 200) : response.body.inspect
         raise Connectors::ApiError.new(

data/lib/connectors/version.rb

@@ -1,3 +1,3 @@
 module Connectors
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/connectors/webhook_context.rb

@@ -1,13 +1,7 @@
 module Connectors
-  # Rich context object passed to `Connector#handle_webhook`. Mirrors n8n's
-  # `IWebhookFunctions` (packages/workflow/src/interfaces.ts:1327-1350): the
-  # handler gets the parsed body AND headers AND query AND a stable
-  # `webhook_name` for multi-webhook providers, without having to thread
-  # `event.request_object.foo` through everywhere.
-  #
-  # Forwards a small set of methods to the underlying `WebhookEvent` so
-  # legacy handlers written against `event.payload_hash` keep working — see
-  # `Connector#handle_webhook` arity detection in `DeliverWebhookJob`.
+  # Request context passed to Connector#handle_webhook. Exposes parsed and
+  # raw body, headers, query and webhook group. Delegates payload aliases
+  # and exposes the persisted WebhookEvent for existing handlers.
   class WebhookContext
     attr_reader :event
 
@@ -15,33 +9,29 @@ module Connectors
       @event = event
     end
 
-    # Parsed body (n8n: `getBodyData()`). Always a Hash — falls back to {}.
+    # Parsed body, with an empty hash fallback.
     def body
       @event.payload_hash
     end
     alias payload      body
     alias payload_hash body
 
-    # Raw (untouched) request body string. nil when the controller couldn't
-    # capture it (form-encoded payloads where Rails consumed the stream).
-    # n8n: `getRequestObject().rawBody`.
+    # Raw request body captured on the persisted event, when available.
     def raw_body
       @event.raw_body
     end
 
-    # All request headers (n8n: `getHeaderData()`). Lowercased keys — same
-    # normalization n8n applies via `req.headers`.
+    # Request headers with lowercase keys.
     def headers
       @event.headers || {}
     end
 
-    # Query string parameters (n8n: `getQueryData()`).
+    # Query string parameters.
     def query
       @event.query || {}
     end
 
-    # Webhook group name that the request hit — `:default` / `:setup` / etc.
-    # n8n: `getWebhookName()`.
+    # Named webhook group, defaulting to :default.
     def webhook_name
       (@event.webhook_name || "default").to_sym
     end

data/lib/connectors/webhook_lifecycle.rb

@@ -2,12 +2,6 @@ module Connectors
   # Runs a connector's webhook_methods callbacks: subscribe = run create
   # (skipping when check_exists already returns true), unsubscribe = run
   # delete. State is persisted into `grant.static_data[group_name]`.
-  #
-  # n8n parity: this is the per-trigger activation orchestration that
-  # `cli/src/active-workflow-runner.ts` performs around each
-  # `INodeType#webhookMethods.default.*` call. We provide it as a connector-
-  # side primitive so the eventual workflow-side activation manager can
-  # call into it without re-implementing the gating.
   class WebhookLifecycle
     def self.subscribe(grant, hook_url:, webhook_name: :default)
       new(grant, webhook_name).subscribe(hook_url: hook_url)
@@ -27,8 +21,7 @@ module Connectors
         )
     end
 
-    # Mirrors n8n: if checkExists returns true, skip create — provider
-    # already has an equivalent subscription. Otherwise run create.
+    # Skip creation when check_exists finds an existing subscription.
     def subscribe(hook_url:)
       result = nil
       @grant.update_static_data!(@webhook_name) do |sub|

data/lib/connectors/webhook_methods.rb

@@ -1,8 +1,5 @@
 module Connectors
-  # Declarative webhook subscription lifecycle. Mirrors n8n's
-  # `INodeType.webhookMethods.default.{checkExists, create, delete}`
-  # (interfaces.ts:2017, 2091-2095; reference impl in
-  # `packages/nodes-base/nodes/Postmark/PostmarkTrigger.node.ts:114-247`).
+  # Declarative webhook subscription callbacks.
   #
   # Provider-specific contract:
   #
@@ -28,8 +25,7 @@ module Connectors
   #   end
   #
   # Multi-webhook providers (Slack has separate `default` event-delivery
-  # group + `setup` URL-verification group — n8n's `webhooks: IWebhookDescription[]`
-  # at interfaces.ts:2600) declare additional named groups:
+  # group + `setup` URL-verification group) declare additional named groups:
   #
   #   webhook_methods :setup    do ... end
   #   webhook_methods :default  do ... end

data/openapi.yaml

@@ -1,23 +1,23 @@
 openapi: 3.1.0
 info:
   title: Connectors Engine API
-  version: "0.1.0"
+  version: "0.1.1"
   description: |
-    Rails engine exposing n8n's connections / credentials layer as a host-mountable API.
+    Rails engine for encrypted credentials, provider authorization, actions, webhooks, polling and remote MCP tools.
     Every endpoint is namespaced under the engine's mount path (default `/connectors`).
 
     **Auth model.** The engine itself doesn't authenticate requests — the host wires
     `Connectors.configuration.current_owner_resolver` to extract the requester from the
     controller (session, JWT, API key — host's choice). Endpoints that mutate
     credentials require an `Owner` to be resolvable; those that read enforce
-    role-based visibility via `principal_resolver` (Phase 9).
+    role-based visibility via `principal_resolver`.
 
     **Source of truth.** This document is hand-maintained alongside the engine.
-    Cross-check against `connectors/config/routes.rb` and the controller files —
+    Cross-check against `config/routes.rb` and the controller files —
     they are the implementation.
 
-    **Mount path.** The host picks where the engine lives. Reference deployment
-    (flow-api) uses `/api/v1/connectors`. The engine introspects its actual
+    **Mount path.** The host chooses the engine mount, such as `/connectors`
+    or `/api/v1/connectors`. The engine introspects its actual
     mount via `Connectors::Engine.mount_path`, so OAuth callback URLs and
     webhook subscribe URLs in responses always reflect reality.
   contact:
@@ -32,7 +32,7 @@ servers:
         default: "http://localhost:3000"
         description: Scheme + host of the host application
       mount:
-        default: "/api/v1/connectors"
+        default: "/connectors"
         description: Path where the host mounts Connectors::Engine
 
 tags:
@@ -281,7 +281,7 @@ paths:
                 type:         { type: string, description: "connector key" }
                 name:         { type: string }
                 data:         { type: object, additionalProperties: true, description: "credential values" }
-                external_ref: { type: string, description: "vault reference (Phase 10)" }
+                external_ref: { type: string, description: "vault reference" }
                 is_managed:   { type: boolean, default: false }
       responses:
         "201":
@@ -804,7 +804,7 @@ paths:
       - { name: webhook_name,  in: path, required: true, schema: { type: string } }
     post:
       tags: [Webhooks]
-      summary: App-level named-group webhook (Phase 7)
+      summary: App-level named-group webhook
       operationId: receiveAppWebhookNamed
       requestBody:
         required: true
@@ -888,12 +888,12 @@ components:
         extends:            { type: array, items: { type: string }, description: "base credential types inherited from" }
         properties:
           type: array
-          description: "n8n INodeProperties array"
+          description: "Credential form field descriptors"
           items: { $ref: "#/components/schemas/Field" }
         authenticate:
           type: object
           nullable: true
-          description: "n8n IAuthenticateGeneric"
+          description: "Declarative credential injection properties"
           properties:
             type:       { type: string, enum: [generic] }
             properties: { type: object, additionalProperties: true }
@@ -960,7 +960,7 @@ components:
 
     Action:
       type: object
-      description: "one thing a connector can DO with a credential (n8n operation / Activepieces action)"
+      description: "A provider operation exposed by a connector"
       properties:
         name:         { type: string, description: "machine key, e.g. send_email" }
         display_name: { type: string }
@@ -973,12 +973,12 @@ components:
           items: { $ref: "#/components/schemas/Field" }
         output:
           type: array
-          description: "shape of the value the action returns (Activepieces returns: …)"
+          description: "Schema of the action result"
           items: { $ref: "#/components/schemas/Field" }
 
     Field:
       type: object
-      description: "n8n INodeProperties — frontend renders the form from this"
+      description: "Input field descriptor used to render a form"
       properties:
         name:             { type: string }
         displayName:      { type: string }
@@ -1011,7 +1011,7 @@ components:
         displayOptions:
           type: object
           additionalProperties: true
-          description: "show/hide rules with _cnd predicates (n8n IDisplayOptions)"
+          description: "Field visibility rules with _cnd predicates"
         options:
           type: array
           items: { type: object, additionalProperties: true }
@@ -1020,7 +1020,7 @@ components:
       type: object
       properties:
         id:                       { type: string, format: uuid }
-        type:                     { type: string, description: "connector key (n8n vocabulary)" }
+        type:                     { type: string, description: "Connector key" }
         connector_key:            { type: string, deprecated: true }
         name:                     { type: string, description: "display name" }
         external_account_id:      { type: string, nullable: true }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: connectors
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Jackson Helio
@@ -23,6 +23,26 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 8.1.3
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement