connectors 0.1.0 → 0.1.1

data/lib/connectors/configuration.rb

@@ -6,13 +6,13 @@ module Connectors
   #   # config/initializers/connectors.rb
   #   Connectors.configure do |c|
   #     c.owner_class_name       = "User"
-  #     c.current_owner_resolver = ->(controller) { controller.current_user }
+  #     c.current_owner_resolver = ->(controller) { controller.request.env["connectors.current_owner"] }
   #     c.host_base_url          = ENV.fetch("APP_BASE_URL", "http://localhost:3000")
   #     c.oauth_credentials = {
   #       slack:  { client_id: ENV["SLACK_CLIENT_ID"],  client_secret: ENV["SLACK_CLIENT_SECRET"] },
   #       linear: { client_id: ENV["LINEAR_CLIENT_ID"], client_secret: ENV["LINEAR_CLIENT_SECRET"] }
   #     }
-  #     c.on_webhook = ->(event) { Inbox::IngestJob.perform_later(event.id) }
+  #     c.on_webhook = ->(event) { ProcessWebhookJob.perform_later(event.id) }
   #   end
   class Configuration
     attr_accessor :owner_class_name,
@@ -58,39 +58,17 @@ module Connectors
       current_owner_resolver.call(controller)
     end
 
-    # The host wires in a block that, given the controller (or any context
-    # with `current_user`/etc.), returns an array of `[principal_type,
-    # principal_id]` pairs representing every identity the requester has
-    # for sharing-visibility purposes.
+    # Resolve managed secrets through the host callback. Returned values
+    # override stored credentials for the lifetime of the Grant instance.
     #
-    # Default: just the owner — `[["<owner_class_name>", owner.id]]`. EE
-    # hosts override to include teams / projects:
-    #
-    #   c.principal_resolver = ->(ctrl) {
-    #     [
-    #       ["User",    ctrl.current_user.id],
-    #       *ctrl.current_user.team_ids.map { |id| ["Team", id] },
-    #     ]
-    #   }
-    # n8n parity: external secrets EE module
-    # (`external-secrets.controller.ee.ts`). Host wires a block that takes a
-    # Grant (one whose `is_managed?` is true) and returns the hash to merge
-    # into the credentials at request time. Returned values overwrite the
-    # DB-stored values for the lifetime of that Grant instance.
-    #
-    #   c.secrets_resolver = ->(grant) {
-    #     vault_client.read("kv/data/connectors/#{grant.connector_key}/#{grant.external_ref}")
-    #   }
+    #   c.secrets_resolver = ->(grant) { vault_client.read(grant.external_ref) }
     def resolve_secrets(grant)
       return {} if secrets_resolver.nil?
       secrets_resolver.call(grant).to_h.transform_keys(&:to_s)
     end
 
-    # Per-connector list of field names sourced from the vault — surfaces
-    # in `GET /connectors/types/:name` as `__overwritten_properties` so the
-    # editor can hide / lock those fields. n8n parity:
-    # `frontend.service.ts:681-705` — same shape, just emitted server-side
-    # instead of recomputed in the editor.
+    # Vault-sourced field names exposed as __overwritten_properties
+    # so clients can display the fields as managed.
     def managed_fields_for(connector_key)
       return [] if secrets_managed_fields_for.nil?
       Array(secrets_managed_fields_for.call(connector_key)).map(&:to_s)
@@ -103,16 +81,8 @@ module Connectors
       [ [ owner.class.name, owner.id ] ]
     end
 
-    # The URL the OAuth provider redirects back to after consent. Defaults
-    # to the engine's own callback path (n8n-style: provider → backend →
-    # render HTML → close popup). For split frontend/backend setups
-    # (Activepieces-style: provider → frontend → POST exchange → backend),
-    # set this to the FRONTEND's callback page, e.g.
-    # `"http://localhost:3001/oauth/callback"`.
-    #
-    # Either way it must MATCH a value registered in the provider's app
-    # console; if it doesn't, Google/Slack/etc. respond with
-    # `redirect_uri_mismatch` before consent even renders.
+    # Use the configured frontend callback URL or the mounted engine callback.
+    # Register the resulting URL with the OAuth provider.
     def resolved_app_callback_url(connector_key)
       return app_callback_url if app_callback_url.present?
       base = host_base_url or

data/lib/connectors/connector.rb

@@ -71,8 +71,7 @@ module Connectors
         @rate_limit_config = { limit: count, per: per }
       end
 
-      # Declarative "Test connection" — mirrors n8n's `ICredentialTestRequest`
-      # (packages/workflow/src/interfaces.ts:340-348). The test fires a real
+      # Declarative connection test. Fires a real
       # HTTP request via the connector's middleware stack (so credentials are
       # injected the same way they would be at runtime) and applies the
       # configured rules to decide pass/fail.
@@ -99,10 +98,6 @@ module Connectors
         }
       end
 
-      # n8n-style declarative auth injection (mirrors `IAuthenticateGeneric`
-      # at packages/workflow/src/interfaces.ts:278-288 + the shape of
-      # `IRequestOptionsSimplifiedAuth` at :197-208).
-      #
       # `properties` accepts any subset of:
       #   headers:                  { "Authorization" => "=Bearer {{$credentials.api_key}}" }
       #   qs:                       { "api_key" => "={{$credentials.api_key}}" }
@@ -118,12 +113,12 @@ module Connectors
       #     headers: { "Authorization" => "=Bearer {{$credentials.api_key}}" }
       #   }
       #
-      # When declared, this replaces the old `api_key_in` imperative shim
+      # When declared, this replaces the imperative `api_key_in` configuration
       # at runtime — both the schema serializer and the Faraday client
       # honor the declarative form first, falling back to `api_key_in` only
       # if `authenticate` is absent.
       def authenticate(type:, properties:)
-        raise ArgumentError, "only type: :generic is supported (n8n's IAuthenticateGeneric)" \
+        raise ArgumentError, "only type: :generic is supported" \
           unless type.to_sym == :generic
         @authenticate_config = { "type" => "generic", "properties" => properties }
       end
@@ -136,15 +131,8 @@ module Connectors
         @authenticate_config || @credential_schema&.resolved_authenticate
       end
 
-      # n8n's `preAuthentication` hook (interfaces.ts:374-377). The block
-      # runs BEFORE each outgoing request, but only when the grant's
-      # credentials look stale (`expires_at` missing or in the past).
-      # Returns a hash merged into the grant's credentials before the
-      # AuthenticateGeneric step injects them into the request.
-      #
-      # Reference impl: CrowdStrikeOAuth2Api.credentials.ts:62-76 —
-      # fetches a session token from /oauth2/token using client_id +
-      # client_secret, returns `{ session_token, expires_at }`.
+      # Run before outgoing requests when expires_at is absent or past.
+      # Merge returned credentials before authentication injection.
       #
       #   pre_authentication do |credentials, helpers|
       #     response = helpers.http_request(
@@ -162,13 +150,11 @@ module Connectors
 
       attr_reader :pre_authentication_block
 
-      # Imperative API-key shim — kept for back-compat with connectors that
-      # declared `api_key_in` before Phase 1. New code should use the
-      # declarative `authenticate` DSL above. When both are declared,
-      # `authenticate` wins.
+      # Imperative API-key injection. A declared authenticate block takes
+      # precedence over this setting.
       #
       #   api_key_in :header, name: "Authorization", prefix: "token "
-      #   api_key_in :query,  name: "api_key"
+      #   api_key_in :query, name: "api_key"
       def api_key_in(location, name:, prefix: nil)
         @api_key_options = { location: location, name: name, prefix: prefix }
       end
@@ -178,14 +164,13 @@ module Connectors
       # Declares OAuth2 provider endpoints + default scope. Client id/secret
       # are supplied by the host via Connectors.configuration.oauth_credentials.
       #
-      # `grant_type:` mirrors n8n's `OAuth2Api.credentials.ts:33-46` enum and
-      # selects the runtime flow:
+      # `grant_type:` selects the runtime flow:
       #   - "authorizationCode" (default) — standard redirect flow
       #   - "clientCredentials"           — server-to-server, no user redirect
       #   - "pkce"                        — RFC 7636 with S256 challenge
       #
       # `authentication:` (header | body) — how client credentials are sent
-      # to the token endpoint. Matches n8n's same-named field. Default
+      # to the token endpoint. Default
       # `"header"` (HTTP Basic).
       #
       #   oauth2 authorize_url: "https://slack.com/oauth/v2/authorize",
@@ -214,8 +199,7 @@ module Connectors
 
       # Declares OAuth1.0a provider endpoints + consumer signature method.
       # Consumer key/secret come from `Connectors.configuration.oauth_credentials`
-      # (same `client_id` / `client_secret` slot as OAuth2 — they're
-      # semantically identical in n8n's storage too).
+      # using the same client_id / client_secret configuration keys as OAuth2.
       #
       #   oauth1 request_token_url: "https://api.twitter.com/oauth/request_token",
       #          authorize_url:     "https://api.twitter.com/oauth/authorize",
@@ -257,10 +241,8 @@ module Connectors
 
       attr_reader :revoke_token_block
 
-      # n8n's `__skipManagedCreation` (frontend.service.ts:707-711). When
-      # an admin disables managed-credential creation for this type, the
-      # editor hides the "Use external secret" toggle AND the API refuses
-      # POSTs that pass `is_managed: true`. Surfaces on the types endpoint.
+      # Disable managed-credential creation in the catalog and API.
+      # Requests passing is_managed: true are rejected for this type.
       def skip_managed_creation!
         @skip_managed_creation = true
       end
@@ -269,16 +251,10 @@ module Connectors
         @skip_managed_creation == true
       end
 
-      # n8n's `genericAuth: boolean` flag on `ICredentialType`
-      # (interfaces.ts:379). Marks the credential as eligible for the future
-      # generic HTTP-Request node's picker. Most provider-specific connectors
-      # leave this off; generic HTTP types (HttpBearerAuth etc.) flip it on.
-      # Connector-level call so non-`extends` connectors can opt in directly:
+      # Enable generic HTTP-request credential use. The setting is also
+      # inherited from base credential schemas.
       #
       #   generic_auth!
-      #
-      # When the connector `extends` an Http*Auth schema, the schema's flag
-      # already propagates — but this stays available as a per-connector override.
       def generic_auth!
         @generic_auth = true
       end
@@ -288,14 +264,10 @@ module Connectors
         @credential_schema&.generic_auth? || false
       end
 
-      # n8n's `supportedNodes: string[]` (interfaces.ts:381). When set, only
-      # the listed node types are allowed to use this credential. Empty/unset
-      # means "any node may use it" — same default as n8n.
+      # Restrict credential use to listed node types; an empty list is unrestricted.
+      # Hosts enforce this through Connectors::PermissionCheck.permit!.
       #
       #   supported_nodes :slack_send_message, :slack_get_channel
-      #
-      # The check itself is `Connectors::PermissionCheck.permit!` — call it
-      # from your node's execution wrapper to enforce.
       def supported_nodes(*names)
         if names.empty?
           @supported_nodes || []
@@ -304,11 +276,7 @@ module Connectors
         end
       end
 
-      # n8n's `httpRequestNode: { name, docsUrl, apiBaseUrl | apiBaseUrlPlaceholder, hidden? }`
-      # (interfaces.ts:380; type `ICredentialHttpRequestNode` at :350-354).
-      # Advertises the connector to the generic HTTP-Request node's
-      # "credential picker" UI — the user sees "Linear API" alongside the
-      # docs link + a pre-filled base URL.
+      # Optional label, documentation and base URL for an HTTP credential picker.
       #
       #   http_request_node name: "Linear API",
       #                     docs_url: "https://developers.linear.app/",
@@ -319,8 +287,7 @@ module Connectors
         # + `docs_url:` + one of the base-URL slots.
         return @http_request_node if name.nil? && docs_url.nil?
         unless api_base_url || api_base_url_placeholder
-          raise ArgumentError, "http_request_node requires either api_base_url or api_base_url_placeholder " \
-                               "(n8n's `ICredentialHttpRequestNode` union, interfaces.ts:350-354)"
+          raise ArgumentError, "http_request_node requires either api_base_url or api_base_url_placeholder"
         end
         @http_request_node = {
           "name"                  => name,
@@ -331,11 +298,8 @@ module Connectors
         }.compact
       end
 
-      # Combined predicate used by `Connectors::PermissionCheck.permit!`.
-      # n8n's logic (oauth/credentials.controller flow, applied at credential
-      # picker render time): if `supportedNodes` is non-empty, the requesting
-      # node must be in it. The generic HTTP-Request node bypasses this
-      # check entirely when `genericAuth` is true on the credential type.
+      # An empty supported_nodes list allows any node. Otherwise require an
+      # allowlist match, with an exception for :http_request when generic_auth is set.
       def supports_node?(node_type)
         node_type = node_type.to_sym
         return true if supported_nodes.empty?           # no allowlist → permitted
@@ -399,12 +363,9 @@ module Connectors
         (@webhook_groups || {}).keys
       end
 
-      # Polling primitive — n8n's `polling: true` flag + `poll()` method
-      # on trigger nodes (interfaces.ts:2060; reference impl
-      # `nodes-base/nodes/Google/Gmail/GmailTrigger.node.ts:65, 281-553`).
-      # The block runs once per scheduler tick (or once per manual POST to
-      # /poll), receives the per-grant scratch hash for cursor persistence,
-      # and returns the new items.
+      # Runs once per host-scheduled poll and returns new items. PollRunner
+      # supplies cursor state scoped to the instance_key, or to the grant
+      # when no instance_key is provided. The host owns scheduling.
       #
       #   polling do |grant, static_data|
       #     since = static_data["last_id"]
@@ -412,9 +373,6 @@ module Connectors
       #     static_data["last_id"] = items.first["id"] if items.any?
       #     items
       #   end
-      #
-      # The scheduler itself is a workflow-roadmap concern; the connector
-      # side just provides the block + cursor contract.
       def polling(&block)
         @polling_block = block
       end
@@ -464,12 +422,8 @@ module Connectors
         end
       end
 
-      # Declarative action manifest — what this connector can DO with a
-      # credential. Mirrors n8n's `(resource, operation)` slot
-      # (packages/workflow/src/interfaces.ts NodeProperties) and Activepieces'
-      # `createAction(...)`. Each action gets a typed param schema, an
-      # optional output schema, and an execute block that runs in the
-      # connector instance's context.
+      # Declare a provider operation with input fields, optional output fields
+      # and an execute block evaluated in the connector instance.
       #
       #   action :send_email,
       #          display_name: "Send Email",
@@ -521,10 +475,8 @@ module Connectors
       @grant = grant
     end
 
-    # The Faraday client with the full middleware stack assembled. When the
-    # connector class (or its inherited credential schema, via Phase 2)
-    # declares an `authenticate` block, AuthenticateGeneric middleware
-    # applies it; otherwise the imperative `auth_scheme` is used.
+    # Build the Faraday middleware stack. A connector or inherited schema
+    # authenticate block takes precedence over the imperative auth_scheme.
     def client
       @client ||= ClientBuilder.new(
         base_url:            self.class.base_url,
@@ -546,13 +498,9 @@ module Connectors
     # the connector opts into polling.
     def poll; end
 
-    # Override in subclass. Called by the webhook dispatcher when an event
-    # arrives for this grant. The argument is a `Connectors::WebhookContext`
-    # (Phase 7) exposing `.body`, `.headers`, `.query`, `.raw_body`,
-    # `.webhook_name`, `.signature`, `.grant`, plus `.event` for direct
-    # access to the persisted `Connectors::WebhookEvent`. The context
-    # delegates `.payload_hash` / `.payload` for back-compat with handlers
-    # written before Phase 7 — the same method works on both.
+    # Override to process a WebhookContext from DeliverWebhookJob.
+    # The context exposes body, headers, query, raw_body, webhook_name,
+    # signature and grant, plus the persisted event and payload aliases.
     def handle_webhook(ctx); end
 
     # Convenience — validates the grant's credentials against the connector's

data/lib/connectors/credential_schema.rb

@@ -1,8 +1,5 @@
 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.
+  # Credential form schema used by client renderers.
   #
   #   credentials do
   #     field :api_key,
@@ -17,12 +14,9 @@ module Connectors
   # 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).
+  # endpoints.
   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.
+    # Supported credential form field types.
     ALLOWED_TYPES = %w[
       string number boolean
       options multiOptions
@@ -43,9 +37,7 @@ module Connectors
         (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.
+      # Serialize form metadata with camelCase field keys for client renderers.
       def to_property
         {
           name:             name.to_s,
@@ -90,7 +82,7 @@ module Connectors
     end
 
     # Inherit fields from one or more registered base credential schemas
-    # (today only `:oauth2`). Inherited fields can be REDECLARED below via
+    # such as :oauth2 or :http_bearer_auth. Redeclare inherited fields 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).
@@ -99,20 +91,15 @@ module Connectors
       @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.
+    # Declare authentication properties inherited by connectors extending
+    # this credential schema.
     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.
+    # Allow generic HTTP-request use and advertise it in the catalog.
     def generic_auth!
       @generic_auth = true
     end
@@ -176,10 +163,8 @@ module Connectors
       @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.
+    # Resolve inherited fields server-side. Children replace parent fields
+    # with the same name, so clients receive a complete form schema.
     def resolved_fields
       parent_fields = @extends.flat_map { |name| CredentialTypeRegistry.fetch(name).own_fields }
       union         = {}
@@ -187,10 +172,8 @@ module Connectors
       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.
+    # Resolve the nearest authenticate declaration, preferring this schema.
+    # Returns nil when no schema in the inheritance chain declares one.
     def resolved_authenticate
       return @authenticate if @authenticate
       @extends.each do |name|

data/lib/connectors/credential_tester.rb

@@ -1,7 +1,6 @@
 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).
+  # provider, applying configured rules to decide pass/fail.
   #
   #   result = CredentialTester.run(grant)
   #   # => { status: "OK", message: "Connection successful" }
@@ -9,8 +8,8 @@ module Connectors
   #   # => { 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.
+  # auto-refresh, rate-limit and error normalization apply. A successful
+  # test verifies this request, not permissions for every provider operation.
   class CredentialTester
     OK    = "OK".freeze
     ERROR = "Error".freeze

data/lib/connectors/credential_type_registry.rb

@@ -1,9 +1,6 @@
 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`.
+  # Registry of reusable credential schemas populated at engine boot.
+  # Connectors inherit registered schemas through extends.
   class CredentialTypeRegistry
     class << self
       def register(name, schema)
@@ -31,10 +28,8 @@ module Connectors
       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).
+    # Base OAuth2 form. Provider connectors can override fields with hidden
+    # defaults to fix their endpoints and other configuration.
     OAUTH2 = CredentialSchema.build do
       field :grant_type,
             type:         "options",
@@ -95,10 +90,8 @@ module Connectors
               { 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.
+      # JWE configuration metadata for form rendering only.
+      # The engine does not decrypt JWE tokens.
       field :jwe_enabled,
             type:         "boolean",
             display_name: "Encrypted Tokens (JWE)",
@@ -114,15 +107,11 @@ module Connectors
             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.
+    # Base OAuth1 form. Client ID and secret represent the consumer key
+    # and secret. Provider connectors can fix endpoint fields with hidden defaults.
     OAUTH1 = CredentialSchema.build do
       display_name      "OAuth1 API"
-      documentation_url "httprequest"
+      documentation_url "https://github.com/jackhelio/connectors/blob/main/CONNECTORS_FRAMEWORK.md#6-built-in-base-credential-types"
       generic_auth!
 
       field :authorization_url,

data/lib/connectors/credential_types/http_auth.rb

@@ -1,29 +1,13 @@
 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`.
+  # Reusable HTTP authentication schemas. Basic, bearer, header and query
+  # types declare runtime injection inherited by extending connectors.
+  # Digest and custom JSON types provide form metadata only.
+  # All types advertise generic_auth for HTTP-request credential selection.
   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.
+    # Basic authentication via the declarative username/password shortcut.
     HTTP_BASIC_AUTH = CredentialSchema.build do
       display_name      "Basic Auth"
-      documentation_url "httprequest"
+      documentation_url "https://github.com/jackhelio/connectors/blob/main/CONNECTORS_FRAMEWORK.md#6-built-in-base-credential-types"
       generic_auth!
 
       field :user,
@@ -41,11 +25,10 @@ module Connectors
       }
     end
 
-    # --- :http_bearer_auth ------------------------------------------------
-    # n8n: HttpBearerAuth.credentials.ts:1-43.
+    # Bearer token authentication.
     HTTP_BEARER_AUTH = CredentialSchema.build do
       display_name      "Bearer Auth"
-      documentation_url "httprequest"
+      documentation_url "https://github.com/jackhelio/connectors/blob/main/CONNECTORS_FRAMEWORK.md#6-built-in-base-credential-types"
       generic_auth!
 
       field :token,
@@ -65,13 +48,10 @@ module Connectors
       }
     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).
+    # Both header name and value are resolved from credential templates.
     HTTP_HEADER_AUTH = CredentialSchema.build do
       display_name      "Header Auth"
-      documentation_url "httprequest"
+      documentation_url "https://github.com/jackhelio/connectors/blob/main/CONNECTORS_FRAMEWORK.md#6-built-in-base-credential-types"
       generic_auth!
 
       field :name,
@@ -94,12 +74,10 @@ module Connectors
       }
     end
 
-    # --- :http_query_auth -------------------------------------------------
-    # n8n: HttpQueryAuth.credentials.ts:1-30. n8n's HTTP node handles
-    # injection imperatively; we synthesize the equivalent generic block.
+    # Query parameter authentication.
     HTTP_QUERY_AUTH = CredentialSchema.build do
       display_name      "Query Auth"
-      documentation_url "httprequest"
+      documentation_url "https://github.com/jackhelio/connectors/blob/main/CONNECTORS_FRAMEWORK.md#6-built-in-base-credential-types"
       generic_auth!
 
       field :name,
@@ -117,19 +95,10 @@ module Connectors
       }
     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.
+    # Digest credential form only; no challenge-response runtime is provided.
     HTTP_DIGEST_AUTH = CredentialSchema.build do
       display_name      "Digest Auth"
-      documentation_url "httprequest"
+      documentation_url "https://github.com/jackhelio/connectors/blob/main/CONNECTORS_FRAMEWORK.md#6-built-in-base-credential-types"
       generic_auth!
 
       field :user,
@@ -142,20 +111,14 @@ module Connectors
             default:      "",
             secret:       true
 
-      # No authenticate block — requires challenge-response middleware
-      # (Faraday-Digest gem or equivalent). Phase 2 ships the schema only.
+      # No authenticate block: digest challenge handling is not implemented.
     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.
+    # Custom JSON credential form only; user-supplied JSON is not
+    # applied to outbound requests by this schema.
     HTTP_CUSTOM_AUTH = CredentialSchema.build do
       display_name      "Custom Auth"
-      documentation_url "httprequest"
+      documentation_url "https://github.com/jackhelio/connectors/blob/main/CONNECTORS_FRAMEWORK.md#6-built-in-base-credential-types"
       generic_auth!
 
       field :json,