connectors 0.1.0

data/lib/connectors/credential_schema.rb

@@ -0,0 +1,219 @@
+module Connectors
+  # Declarative description of every field a credential type's data hash can
+  # contain. Mirrors n8n's `INodeProperties` shape exactly (n8n source:
+  # packages/workflow/src/interfaces.ts:1773-1812) so a single frontend
+  # renderer handles every connector with no per-connector logic.
+  #
+  #   credentials do
+  #     field :api_key,
+  #           type:         "string",
+  #           display_name: "API Key",
+  #           required:     true,
+  #           type_options: { password: true },
+  #           placeholder:  "re_...",
+  #           description:  "Generate at https://resend.com/api-keys"
+  #   end
+  #
+  # Inheritance: a connector can `extends :oauth2` (or any other registered
+  # base type) and `field` calls in the block can REDECLARE inherited fields
+  # — typically as `type: "hidden"` with a fixed `default:` to lock provider
+  # endpoints (matches n8n's Slack/Google override pattern at
+  # SlackOAuth2Api.credentials.ts:38-122).
+  class CredentialSchema
+    # n8n's `NodePropertyTypes` enum (interfaces.ts:1561-1584). Wave A ships
+    # the most commonly-used subset; later waves add resourceLocator /
+    # collection / fixedCollection / dateTime as connectors demand them.
+    ALLOWED_TYPES = %w[
+      string number boolean
+      options multiOptions
+      json hidden notice
+    ].freeze
+
+    Field = Struct.new(
+      :name, :display_name, :type, :default, :placeholder, :description, :hint,
+      :required, :no_data_expression,
+      :type_options, :display_options, :options,
+      keyword_init: true
+    ) do
+      def required?
+        required == true
+      end
+
+      def password?
+        (type_options || {}).any? { |k, v| k.to_s == "password" && v == true }
+      end
+
+      # Frontend-shaped hash. n8n serializes property names in camelCase
+      # (`displayName`, `typeOptions`); we mirror that so the editor's
+      # generic form renderer eats it without translation.
+      def to_property
+        {
+          name:             name.to_s,
+          displayName:      display_name || name.to_s.tr("_", " ").capitalize,
+          type:             type.to_s,
+          default:          default,
+          placeholder:      placeholder,
+          description:      description,
+          hint:             hint,
+          required:         required == true,
+          noDataExpression: no_data_expression == true,
+          typeOptions:      stringify(type_options),
+          displayOptions:   stringify(display_options),
+          options:          options&.map { |o| stringify(o) }
+        }.compact
+      end
+
+      private
+
+      def stringify(v)
+        case v
+        when Hash  then v.each_with_object({}) { |(k, vv), out| out[k.to_s] = stringify(vv) }
+        when Array then v.map { |vv| stringify(vv) }
+        else v
+        end
+      end
+    end
+
+    def self.build(&block)
+      schema = new
+      schema.instance_eval(&block) if block
+      schema
+    end
+
+    def initialize
+      @fields          = {}
+      @extends         = []
+      @authenticate    = nil
+      @generic_auth    = false
+      @display_name    = nil
+      @documentation_url = nil
+    end
+
+    # Inherit fields from one or more registered base credential schemas
+    # (today only `:oauth2`). Inherited fields can be REDECLARED below via
+    # `field` — typically as `type: "hidden", default: "..."` to lock
+    # provider-specific endpoints. Doubles as a getter when called with
+    # no args (the serializer needs to read it back).
+    def extends(*base_names)
+      return @extends if base_names.empty?
+      @extends = base_names.flatten.map(&:to_sym)
+    end
+
+    # n8n-shape declarative auth injection (mirrors `ICredentialType.authenticate`
+    # at packages/workflow/src/interfaces.ts:367; type `IAuthenticateGeneric`
+    # at :278-288). Per-credential-type so any connector that `extends` this
+    # schema inherits the injection contract automatically.
+    def authenticate(type: nil, properties: nil)
+      return @authenticate if type.nil? && properties.nil?
+      raise ArgumentError, "authenticate type: must be :generic" unless type.to_sym == :generic
+      @authenticate = { "type" => "generic", "properties" => properties }
+    end
+
+    # n8n flag: this credential type is visible to the future generic HTTP
+    # Request node's credential picker (`interfaces.ts:379`; example
+    # consumer `HttpBearerAuth.credentials.ts:12`). Stored here so the
+    # serializer surfaces it; runtime enforcement lands in Phase 5.
+    def generic_auth!
+      @generic_auth = true
+    end
+
+    def generic_auth?
+      @generic_auth == true || @extends.any? { |b| CredentialTypeRegistry.fetch(b).generic_auth? rescue false }
+    end
+
+    # Optional metadata that lives on the credential type rather than the
+    # connector class. Set on base credential types (HttpBearerAuth's
+    # "Bearer Auth" name) — the serializer prefers these over connector-
+    # level fallbacks when present.
+    def display_name(value = nil)
+      return @display_name if value.nil?
+      @display_name = value.to_s
+    end
+
+    def documentation_url(value = nil)
+      return @documentation_url if value.nil?
+      @documentation_url = value.to_s
+    end
+
+    def field(name,
+              type:               "string",
+              display_name:       nil,
+              default:            nil,
+              placeholder:        nil,
+              description:        nil,
+              hint:               nil,
+              required:           false,
+              no_data_expression: false,
+              secret:             false,     # convenience — sets type_options[:password] = true
+              type_options:       nil,
+              display_options:    nil,
+              options:            nil)
+      raise ArgumentError, "unknown credential field type #{type.inspect}; allowed: #{ALLOWED_TYPES.inspect}" \
+        unless ALLOWED_TYPES.include?(type.to_s)
+
+      effective_type_options = (type_options || {}).dup
+      effective_type_options[:password] = true if secret
+
+      @fields[name.to_sym] = Field.new(
+        name:               name.to_sym,
+        display_name:       display_name,
+        type:               type.to_s,
+        default:            default,
+        placeholder:        placeholder,
+        description:        description,
+        hint:               hint,
+        required:           required,
+        no_data_expression: no_data_expression,
+        type_options:       effective_type_options.empty? ? nil : effective_type_options,
+        display_options:    display_options,
+        options:            options
+      )
+    end
+
+    # The fields declared directly on this schema, in declaration order.
+    # For the full resolved form (parents + own), use `resolved_fields`.
+    def own_fields
+      @fields.values
+    end
+
+    # n8n's editor walks `extends` and merges parent properties before
+    # rendering. We do the walk server-side and emit the union so the
+    # frontend doesn't need to fetch each parent type separately. Children
+    # override parents by re-declaring with the same name.
+    def resolved_fields
+      parent_fields = @extends.flat_map { |name| CredentialTypeRegistry.fetch(name).own_fields }
+      union         = {}
+      (parent_fields + own_fields).each { |f| union[f.name] = f }
+      union.values
+    end
+
+    # Walk `extends` to find the inherited authenticate block; the child's
+    # own block (if declared) overrides. Returns nil when no parent in the
+    # chain declared one. Matches n8n's runtime credential-walker pattern
+    # at packages/cli/src/credential-types.ts:26-37.
+    def resolved_authenticate
+      return @authenticate if @authenticate
+      @extends.each do |name|
+        parent = CredentialTypeRegistry.fetch(name) rescue nil
+        next if parent.nil?
+        block = parent.resolved_authenticate
+        return block if block
+      end
+      nil
+    end
+
+    # Back-compat — older code referenced `.fields` and `.required_fields`.
+    alias_method :fields, :resolved_fields
+
+    def required_fields
+      resolved_fields.select(&:required?)
+    end
+
+    def validate!(credentials_hash)
+      data    = (credentials_hash || {}).transform_keys(&:to_s)
+      missing = required_fields.map { |f| f.name.to_s }.reject { |k| data[k].to_s.length.positive? }
+      raise MissingCredentialFields.new(missing) if missing.any?
+      true
+    end
+  end
+end

data/lib/connectors/credential_tester.rb

@@ -0,0 +1,85 @@
+module Connectors
+  # Executes a connector's `test_request` declaration against the live
+  # provider, applying configured rules to decide pass/fail. Mirrors n8n's
+  # `CredentialsTester` (packages/cli/src/services/credentials-tester.service.ts).
+  #
+  #   result = CredentialTester.run(grant)
+  #   # => { status: "OK", message: "Connection successful" }
+  #   # or
+  #   # => { status: "Error", message: "Slack token is invalid", details: {...} }
+  #
+  # Reuses the connector's Faraday client so the same auth middleware,
+  # auto-refresh, rate-limit, and error-normalization apply — a test that
+  # passes here means a real request will pass too.
+  class CredentialTester
+    OK    = "OK".freeze
+    ERROR = "Error".freeze
+
+    def self.run(grant)
+      new(grant).run
+    end
+
+    def initialize(grant)
+      @grant = grant
+      @klass = grant.connector.class
+      @cfg   = @klass.test_request_config
+    end
+
+    def run
+      return inconclusive("No test_request declared for #{@klass.connector_key}") if @cfg.nil?
+
+      response = issue_request
+      verdict_for(response)
+    rescue Connectors::AuthenticationFailed => e
+      { status: ERROR, message: e.message }
+    rescue Connectors::ApiError => e
+      { status: ERROR, message: e.message, details: { status: e.respond_to?(:status) ? e.status : nil } }
+    rescue => e
+      { status: ERROR, message: "#{e.class}: #{e.message}" }
+    end
+
+    private
+
+    def issue_request
+      client = @grant.connector.client
+      client.public_send(@cfg[:method], @cfg[:url], @cfg[:query]) do |req|
+        (@cfg[:headers] || {}).each { |k, v| req.headers[k] = v }
+      end
+    end
+
+    def verdict_for(response)
+      expected = @cfg[:expect_status]
+      if expected && response.status.to_i != expected.to_i
+        return { status: ERROR, message: "Expected HTTP #{expected}, got #{response.status}" }
+      end
+
+      Array(@cfg[:rules]).each do |rule|
+        verdict = apply_rule(rule, response)
+        return verdict if verdict
+      end
+
+      { status: OK, message: "Connection successful" }
+    end
+
+    # Each rule short-circuits with an Error verdict when it matches the
+    # failure condition; returns nil to mean "this rule said nothing, keep
+    # going".
+    def apply_rule(rule, response)
+      case rule[:type].to_sym
+      when :response_code
+        return nil if response.status.to_i == rule[:value].to_i
+        { status: ERROR, message: rule[:message] || "Unexpected status #{response.status}" }
+      when :response_success_body
+        actual = response.body.is_a?(Hash) ? response.body[rule[:key].to_s] : nil
+        return nil unless actual == rule[:value]
+        { status: ERROR, message: rule[:message] || "Response body indicated failure" }
+      else
+        raise Connectors::Error, "unknown test rule type #{rule[:type].inspect}"
+      end
+    end
+
+    def inconclusive(msg)
+      { status: ERROR, message: msg, details: { kind: "test_not_configured" } }
+    end
+  end
+end

data/lib/connectors/credential_type_registry.rb

@@ -0,0 +1,162 @@
+module Connectors
+  # Registry of reusable base credential schemas that connectors `extends`.
+  # Mirrors n8n's pattern where every OAuth2 provider extends a single
+  # canonical `OAuth2Api` credential type (packages/nodes-base/credentials/
+  # OAuth2Api.credentials.ts:1-238). The registry is populated at engine
+  # boot — see `Connectors::Engine`.
+  class CredentialTypeRegistry
+    class << self
+      def register(name, schema)
+        store[name.to_sym] = schema
+      end
+
+      def fetch(name)
+        store.fetch(name.to_sym) do
+          raise Error.new("unknown base credential type #{name.inspect}; known: #{store.keys.inspect}")
+        end
+      end
+
+      def all
+        store.dup
+      end
+
+      def clear!
+        store.clear
+      end
+
+      private
+
+      def store
+        @store ||= {}
+      end
+    end
+
+    # Canonical OAuth2 credential schema — every OAuth2 provider connector
+    # extends this and overrides specific fields as `type: "hidden"` with a
+    # fixed `default`. Field set matches n8n's OAuth2Api credentials type
+    # (packages/nodes-base/credentials/OAuth2Api.credentials.ts:1-238).
+    OAUTH2 = CredentialSchema.build do
+      field :grant_type,
+            type:         "options",
+            display_name: "Grant Type",
+            default:      "authorizationCode",
+            required:     true,
+            description:  "OAuth2 grant flow to use.",
+            options: [
+              { name: "Authorization Code",      value: "authorizationCode" },
+              { name: "Client Credentials",      value: "clientCredentials" },
+              { name: "Authorization Code (PKCE)", value: "pkce" }
+            ]
+
+      field :authorization_url,
+            type:         "string",
+            display_name: "Authorization URL",
+            required:     true,
+            placeholder:  "https://example.com/oauth/authorize",
+            display_options: { show: { grant_type: %w[authorizationCode pkce] } }
+
+      field :access_token_url,
+            type:         "string",
+            display_name: "Access Token URL",
+            required:     true,
+            placeholder:  "https://example.com/oauth/token"
+
+      field :client_id,
+            type:         "string",
+            display_name: "Client ID",
+            required:     true
+
+      field :client_secret,
+            type:         "string",
+            display_name: "Client Secret",
+            required:     true,
+            secret:       true
+
+      field :scope,
+            type:         "string",
+            display_name: "Scope",
+            default:      "",
+            description:  "Space-separated list of OAuth scopes to request."
+
+      field :auth_query_parameters,
+            type:         "string",
+            display_name: "Auth URI Query Parameters",
+            default:      "",
+            description:  "Additional query parameters appended to the authorize URL " \
+                          "(e.g., `access_type=offline&prompt=consent`)."
+
+      field :authentication,
+            type:         "options",
+            display_name: "Authentication",
+            default:      "header",
+            description:  "How the client_id / client_secret are sent during token exchange.",
+            options: [
+              { name: "Header",          value: "header" },
+              { name: "Body",            value: "body" }
+            ]
+
+      # Phase 11 polish — OAuth2 advanced fields. n8n parity:
+      # `OAuth2Api.credentials.ts:208-237`. Form-only at the engine level
+      # (no runtime JWE decryption); ship the schema so the editor can
+      # render the configuration UI for enterprise SSO scenarios.
+      field :jwe_enabled,
+            type:         "boolean",
+            display_name: "Encrypted Tokens (JWE)",
+            default:      false,
+            description:  "Whether the IdP returns tokens encrypted as JWE to the public key at this " \
+                          "instance's JWKS endpoint."
+      field :jwks_uri,
+            type:         "string",
+            display_name: "JWKS URI",
+            default:      "",
+            description:  "Provide this URL to your IdP so it can fetch the public key used to " \
+                          "encrypt access and ID tokens for this instance.",
+            display_options: { show: { jwe_enabled: [ true ] } }
+    end
+
+    # n8n's canonical `OAuth1Api` credential type
+    # (packages/nodes-base/credentials/OAuth1Api.credentials.ts:1-72). Same
+    # storage shape as OAuth2's `client_id` / `client_secret` — they map to
+    # the `consumerKey` / `consumerSecret` here. Connectors that extend this
+    # type generally `field :authorization_url, type: "hidden", default: "..."`
+    # to lock the provider endpoint.
+    OAUTH1 = CredentialSchema.build do
+      display_name      "OAuth1 API"
+      documentation_url "httprequest"
+      generic_auth!
+
+      field :authorization_url,
+            type:         "string",
+            display_name: "Authorization URL",
+            required:     true
+      field :access_token_url,
+            type:         "string",
+            display_name: "Access Token URL",
+            required:     true
+      field :request_token_url,
+            type:         "string",
+            display_name: "Request Token URL",
+            required:     true
+      field :consumer_key,
+            type:         "string",
+            display_name: "Consumer Key",
+            required:     true,
+            secret:       true
+      field :consumer_secret,
+            type:         "string",
+            display_name: "Consumer Secret",
+            required:     true,
+            secret:       true
+      field :signature_method,
+            type:         "options",
+            display_name: "Signature Method",
+            required:     true,
+            default:      "HMAC-SHA1",
+            options: [
+              { name: "HMAC-SHA1",   value: "HMAC-SHA1" },
+              { name: "HMAC-SHA256", value: "HMAC-SHA256" },
+              { name: "HMAC-SHA512", value: "HMAC-SHA512" }
+            ]
+    end
+  end
+end

data/lib/connectors/credential_types/http_auth.rb

@@ -0,0 +1,171 @@
+module Connectors
+  # Generic HTTP authentication credential types — n8n parity with the six
+  # `Http*Auth.credentials.ts` types shipped in
+  # `packages/nodes-base/credentials/`. Each is `generic_auth: true` so a
+  # future HTTP-Request-style node can offer them in its credential picker
+  # (the runtime check lands in Phase 5).
+  #
+  # Connectors inherit any of these via `extends :http_bearer_auth` etc.
+  # When a connector extends one of the runtime-supported types
+  # (basic / bearer / header / query), the AuthenticateGeneric middleware
+  # picks up the inherited `authenticate` block and injects per-request —
+  # no `api_key_in` boilerplate needed.
+  #
+  # n8n source: `packages/nodes-base/credentials/HttpBasicAuth.credentials.ts`,
+  # `HttpBearerAuth.credentials.ts`, `HttpHeaderAuth.credentials.ts`,
+  # `HttpQueryAuth.credentials.ts`, `HttpDigestAuth.credentials.ts`,
+  # `HttpCustomAuth.credentials.ts`.
+  module CredentialTypes
+    # --- :http_basic_auth -------------------------------------------------
+    # n8n: HttpBasicAuth.credentials.ts:1-33. n8n's HTTP node implements
+    # Basic auth itself (no `authenticate` block on the credential). We
+    # synthesize one using AuthenticateGeneric's `auth: { username, password }`
+    # shortcut so the declarative path works end-to-end.
+    HTTP_BASIC_AUTH = CredentialSchema.build do
+      display_name      "Basic Auth"
+      documentation_url "httprequest"
+      generic_auth!
+
+      field :user,
+            type:         "string",
+            display_name: "User",
+            default:      ""
+      field :password,
+            type:         "string",
+            display_name: "Password",
+            default:      "",
+            secret:       true
+
+      authenticate type: :generic, properties: {
+        auth: { username: "={{$credentials.user}}", password: "={{$credentials.password}}" }
+      }
+    end
+
+    # --- :http_bearer_auth ------------------------------------------------
+    # n8n: HttpBearerAuth.credentials.ts:1-43.
+    HTTP_BEARER_AUTH = CredentialSchema.build do
+      display_name      "Bearer Auth"
+      documentation_url "httprequest"
+      generic_auth!
+
+      field :token,
+            type:         "string",
+            display_name: "Bearer Token",
+            default:      "",
+            secret:       true
+
+      field :_notice_custom_auth,
+            type:         "notice",
+            display_name: 'This credential uses the "Authorization" header. ' \
+                          'To use a custom header, use a "Header Auth" credential instead',
+            default:      ""
+
+      authenticate type: :generic, properties: {
+        headers: { "Authorization" => "=Bearer {{$credentials.token}}" }
+      }
+    end
+
+    # --- :http_header_auth ------------------------------------------------
+    # n8n: HttpHeaderAuth.credentials.ts:1-45. Both header NAME and VALUE
+    # are templated — AuthInjection.walk resolves keys as well as values
+    # (see auth_injection.rb).
+    HTTP_HEADER_AUTH = CredentialSchema.build do
+      display_name      "Header Auth"
+      documentation_url "httprequest"
+      generic_auth!
+
+      field :name,
+            type:         "string",
+            display_name: "Name",
+            default:      ""
+      field :value,
+            type:         "string",
+            display_name: "Value",
+            default:      "",
+            secret:       true
+
+      field :_notice_multi,
+            type:         "notice",
+            display_name: 'To send multiple headers, use a "Custom Auth" credential instead',
+            default:      ""
+
+      authenticate type: :generic, properties: {
+        headers: { "={{$credentials.name}}" => "={{$credentials.value}}" }
+      }
+    end
+
+    # --- :http_query_auth -------------------------------------------------
+    # n8n: HttpQueryAuth.credentials.ts:1-30. n8n's HTTP node handles
+    # injection imperatively; we synthesize the equivalent generic block.
+    HTTP_QUERY_AUTH = CredentialSchema.build do
+      display_name      "Query Auth"
+      documentation_url "httprequest"
+      generic_auth!
+
+      field :name,
+            type:         "string",
+            display_name: "Name",
+            default:      ""
+      field :value,
+            type:         "string",
+            display_name: "Value",
+            default:      "",
+            secret:       true
+
+      authenticate type: :generic, properties: {
+        qs: { "={{$credentials.name}}" => "={{$credentials.value}}" }
+      }
+    end
+
+    # --- :http_digest_auth ------------------------------------------------
+    # n8n: HttpDigestAuth.credentials.ts:1-32. n8n consumes this via axios's
+    # built-in digest challenge handling. Faraday has no equivalent
+    # middleware out of the box — we ship the SCHEMA (so the frontend can
+    # render the form + a future generic HTTP-Request node can offer the
+    # type) but the AuthenticateGeneric middleware can't perform the
+    # challenge-response handshake on its own.
+    #
+    # Runtime support requires a Faraday-Digest middleware. Tracked as a
+    # follow-up; for now the type is form-only.
+    HTTP_DIGEST_AUTH = CredentialSchema.build do
+      display_name      "Digest Auth"
+      documentation_url "httprequest"
+      generic_auth!
+
+      field :user,
+            type:         "string",
+            display_name: "User",
+            default:      ""
+      field :password,
+            type:         "string",
+            display_name: "Password",
+            default:      "",
+            secret:       true
+
+      # No authenticate block — requires challenge-response middleware
+      # (Faraday-Digest gem or equivalent). Phase 2 ships the schema only.
+    end
+
+    # --- :http_custom_auth ------------------------------------------------
+    # n8n: HttpCustomAuth.credentials.ts:1-29. Single `json` field carrying
+    # `{ headers, body, qs }`. n8n's HTTP node parses this JSON at request
+    # time and applies it. Our AuthenticateGeneric middleware works on a
+    # static `properties` block; runtime injection of a user-supplied JSON
+    # is deferred until a Custom-API-Call style node lands (workflow
+    # roadmap). Phase 2 ships the schema only.
+    HTTP_CUSTOM_AUTH = CredentialSchema.build do
+      display_name      "Custom Auth"
+      documentation_url "httprequest"
+      generic_auth!
+
+      field :json,
+            type:         "json",
+            display_name: "JSON",
+            required:     true,
+            default:      "",
+            description:  "Use JSON to specify authentication values for headers, body and qs.",
+            placeholder:  '{ "headers": { "key" : "value" }, "body": { "key": "value" }, "qs": { "key": "value" } }',
+            type_options: { redactJsonLeaves: true }
+    end
+  end
+end