Repository navigation
fix(source, connection): source auth flags on WEBHOOK sources, retry status code ranges, and related upsert fixes - #496
Merged
Merged
Conversation
The API validates config.auth on WEBHOOK and HTTP sources against the
method named in config.auth_type, and rejects auth without it with
"config.auth is not allowed". The CLI only added auth_type for HTTP, so
--api-key / --source-api-key (and --basic-auth-*, --hmac-*,
--webhook-secret) failed with 422 on WEBHOOK sources.
- Generalize ensureSourceConfigAuthTypeForHTTP to ensureSourceConfigAuthType
for WEBHOOK and HTTP, and call it inside the shared config builders so
flag and --config/--config-file paths both get it.
- Infer STANDARD_WEBHOOKS for a bare webhook_secret_key (HMAC requires
algorithm/encoding/header_key, so that shape can only be Standard
Webhooks); keep HMAC when those fields are present.
- source update without --type: the API rejects config sent without type
("config is not allowed"), so look up the stored source and send its
type, which also selects the auth_type to infer.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0172mwz15DSjQ64NaYbtyCxw
…atus-codes The flag only accepted integers, so "429,500-599" failed client-side even though the API (and --rules JSON) accept range, comparison and exclusion expressions. Validate each entry against the API's RetryRule response_status_codes pattern instead, and document the forms in the flag help. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0172mwz15DSjQ64NaYbtyCxw
… path Follow-up from review of the auth_type fix, which left paths that still failed with "config.auth is not allowed": - source upsert without --type: the API upserts as WEBHOOK, so config is now built for WEBHOOK. - connection upsert of a new connection with --source-name but no --source-type: sent source.type "" (rejected by the API); now WEBHOOK. - connection upsert partial source update (--source-* flags only): built config with an empty type and merged it over the stored config, whose auth_type comes back without credentials. Now built for the stored type, and the stored auth_type is dropped unless its auth is sent too (sending it bare failed with "source.config.auth is required"). - source update without --type: rebuild config for the stored type, so the auth shape matches it, not only auth_type. auth_type inference now reads each source type's methods from the cached OpenAPI spec (pkg/cmd/sources/auth_methods.go) instead of a WEBHOOK/HTTP list, covering ORDINAL, AZURE_EVENT_GRID, SENDGRID_INBOUND, PROMETHEUS_ALERTMANAGER, BETTER_STACK, GRAFANA and GITLAB. The method is the best fit for the auth keys; ties are left to the API. WEBHOOK/HTTP keep a built-in table when the spec cannot be fetched. Also: document auth_type inference (including bare webhook_secret_key -> STANDARD_WEBHOOKS) in command help, reject more than the API's 10 response_status_codes client-side, and add command-level tests against a stub API plus acceptance tests for the WEBHOOK auth and retry range paths. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0172mwz15DSjQ64NaYbtyCxw
PUT /sources validates with the API's source create schema, where type defaults to WEBHOOK. `gateway source upsert <name>` sent no type when --type was omitted, so upserting an existing STRIPE source with only --description converted it into a WEBHOOK source: same id, default WEBHOOK allowed methods, verification gone. When --type is omitted, look the source up by name (including disabled sources) and send its stored type, building config (and inferring auth_type) for that type. When no source has the name, nothing changes: no type is sent, config is built for WEBHOOK, and the API creates a WEBHOOK source. If the lookup fails, the command fails rather than falling back to the typeless request that converts the source. This mirrors connection upsert, which fills a missing inline source type from the existing connection. The upsert Long help now says how the type is chosen instead of warning about the conversion, and REFERENCE.md is regenerated. The stub-API harness gains stubStatus so a test can fail the lookup. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0172mwz1hz2ZKGd77wwmvG5h
The spec-driven auth check behind `source create/upsert` and
`connection create` had been off since the API moved to 2026-09-01.
parseOpenAPISpec read components.schemas.SourceCreateRequest, which the
spec no longer has, so FetchSourceTypes returned an empty map. That map
was cached for 24 hours, every type lookup missed, and
validateSourceAuthFromSpec returned nil. The tests stayed green because
their mock spec still used the old shape.
Parse the SourceTypeConfig<TYPE> schemas instead, reusing the
auth_methods.go schema types. For each source type: its name as the API
spells it (x-docs-type, so PROPERTY-FINDER), the fields its config.auth
takes and requires, and whether auth is required.
The per-type schema is shared by request and response, so its auth is
always nullable. The request rule shows up only as x-required on the
type's SourceTypeConfig.oneOf entry. The server sets that when any
feature is required, a handshake included. So auth counts as required
when x-required is set, the type has one fixed method (the API always
accepts auth_type null for a choice of method), and that method has
fields (handshake-only types like STRAVA have none). Against the live
spec this gives exactly the server's 26 verification-required types,
plus ONFLEET (handshake required, verification optional), which
optionalAuthSourceTypes now lists in place of STRIPE. STRIPE's auth is
now read as optional from the spec.
validateSourceAuthFromSpec drops the AuthScheme switch. The spec has no
such field, and the old parser invented it. It now builds the
config.auth the flags would send (sourceAuthFromFlags, extracted from
the builder) and checks it against the type's fields:
- no auth flag for a type requiring auth: name the flag that sets the
fields, or --config when none does (ALIPAY's public_key)
- an auth flag missing a required field (--api-key for STRIPE): the API
strips the keys a type does not take, then rejects the request
An empty or failed parse is now an error and is never cached. An empty
cache file is never served. The cache file name gains "_v2", so the
`{}` the old parser cached under the current name is not read.
types_test.go now runs against the fixture cut from the real spec. The
fixture gains the SourceTypeConfig umbrella with its x-required markers,
plus types covering each case: required (CLOUDSIGNAL, ALIPAY,
TIKTOK_SHOP, VERCEL_LOG_DRAINS), optional (GITHUB, POSTMARK, ACUMATICA)
and handshake (ONFLEET, STRAVA). The pkg/cmd tests serve the same
fixture, and command-level tests check that a rejected create or
upsert sends no request.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0172mwz23fhwEFwmLFdWoEbX
…rce is given inline `connection upsert <name> --source-name X --source-type WEBHOOK` on an existing connection, with no destination flags, failed with 422 "value must contain at least one of [destination_id, destination]". needsExistingConnection() skipped the lookup for that flag combination, so buildUpsertRequest got existing == nil and its fallback that carries the stored destination over by ID never ran. The same was true the other way round: an inline destination with no source flags sent no source. The lookup now runs whenever either side is not named by the flags (no --*-id, --*-name or --*-type). That replaces the no-flags and config-only conditions, which it covers. Tests: - command-level tests against a stub API assert the PUT /connections body carries destination_id (inline source) and source_id (inline destination) - needsExistingConnection cases for both sides and for --source-id - acceptance test under the connection_upsert tag Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0172mwz1iqs4Qa9xmLagyE3v
…ection up connection upsert took the first model returned by the connections list `name` filter without comparing names. The API filter is exact and case-sensitive today (checked against the live API), but its spec only says "Filter by connection name", so a partial or case-different match could silently select the wrong connection. Add Client.FindConnectionByName which compares the name again. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
--webhook-secret, --hmac-secret and --api-key sent one generic shape to every type. The API stores the keys a type's auth schema lists and lays them over the provider's defaults when it verifies a request, so a generic header_key replaced VAPI's x-signature and FORMSTACK's x-fs-signature. Types with a choice of method (GITLAB, GRAFANA, PROMETHEUS_ALERTMANAGER, BETTER_STACK, ORDINAL) got an auth block with no auth_type and a 422. The flags now read the type's methods from the spec: the secret alone unless the method requires the HMAC settings (WEBHOOK and HTTP keep sha256/hex/x-webhook-signature), auth_type set to the method used, and --api-key refused where the type needs its own header name. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
downloadOpenAPISpec used http.Get with no timeout, and source types and auth methods kept separate caches, so a cold cache downloaded the 1.3 MB spec twice. The download now gives up after 10 seconds, and each fetch also fills the other cache from the same download. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The help said a bare webhook_secret_key resolves to STANDARD_WEBHOOKS, but --webhook-secret sends the HMAC shape on WEBHOOK; only --config reaches STANDARD_WEBHOOKS. It also named WEBHOOK and HTTP as the types that infer auth_type, which overstated it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…estination change is ignored The API never changes an existing connection's source or destination, but connection upsert and update sent the change and printed success, and upsert also left an inline destination behind unattached. - upsert looks the connection up whenever a source or destination is named by ID or name, and fails before any write (including the inline destination upsert) if it differs from the stored one. Dry-run reports the same error. - update checks --source-id and --destination-id against the stored connection and errors when they differ; matching values are accepted and not sent. The flags are kept rather than removed, because removing them would be a breaking change. - the gateway_connections_write MCP tool applies the same check to its upsert and update actions. Fixes #466 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e live API Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
connection upsert only set the request's rules when the built list was non-empty, so --rules '[]' or an empty --rules-file left the stored rules in place while reporting success. Key it off whether the flag was given, as connection update does, and say in the dry run that the rules will be cleared. Fixes #472 (point 2; points 1 and 3 were fixed separately) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…t without --type The code fix for dropped --url/--cli-path when --type is omitted is already on this branch (the stored type is resolved once, for update and upsert alike). What the issue asked for and was missing is the acceptance test that reads the destination back: update --url, update --cli-path, upsert --url, a negative control that an update without --url leaves the URL alone, and a mismatched --url on a CLI destination that must be refused rather than dropped. Refs #406 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…uilder webhook_secret, api_key, basic_auth and hmac in --config still produced the generic shape, so webhook_secret on VAPI stored header_key x-webhook-signature and broke verification. They now go through the same builder as the flags, with the same refusals and offline fallback. The webhook secret flag descriptions no longer say e.g. Stripe. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tion Checked against the live API after the destination guard landed: upsert keys on source and name together, so naming a different source creates a second connection with the same name rather than re-pointing the stored one, and that connection may have any destination. Refusing it broke an existing acceptance test and a working feature. - SelectConnectionForUpsert picks the stored connection by the source the caller names, and reports when the source differs; the destination guard is skipped in that case (CLI and MCP). - Several connections with the same name and no source named is now an error rather than silently picking the first. - Reword the update and MCP text: update ignores a new source as well as a new destination, upsert only ignores a new destination. Refs #466 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…erate REFERENCE.md Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ts own algorithm Refusing the flag broke commands that worked before, such as connection create --source-type TWILIO --source-hmac-algo sha1: the API dropped the algorithm and the provider's own one applied. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes #341, fixes #412, fixes #406, fixes #466, fixes #472.
Fixes two bugs found while live-testing a runbook with CLI v3.1.0 against API version 2026-09-01, plus the related problems that turned up while fixing and reviewing them.
Reported bugs
--source-api-key/--api-keyfailed withconfig.auth is not allowed, and so did the basic auth, HMAC and--webhook-secretflags. The API checksconfig.authagainst the method named inconfig.auth_typefor any source type that offers a choice of verification method, and the CLI only sentauth_typefor HTTP. The CLI now infersauth_typeon every source-config path: flags,--config/--config-file,--source-config, create/upsert/update, inline connection sources and partial updates.pkg/cmd/sources/auth_methods.go) and picks the method whose fields best fit the auth keys. WEBHOOK and HTTP have a built-in table for when the spec can't be fetched.auth_typeis left unset and the API reports the error.--rule-retry-response-status-codes "429,500-599"was rejected client-side. Each entry is now validated against the API's ownresponse_status_codespattern, so codes, ranges, comparisons (>400) and exclusions (!401) are accepted, up to the API's limit of 10 entries. The flag help is updated.Related fixes
source upsertwithout--typesilently converted an existing non-WEBHOOK source to WEBHOOK and dropped its verification.PUT /sourcesdefaults a missingtypeto WEBHOOK. The CLI now looks the source up by name and sends its stored type.source updatewith config flags but no--typefailed withconfig is not allowed. The CLI now sends the stored type and builds the config for it.connection upsertwith only--source-*config flags on an existing connection failed. The storedauth_typecame back without its credentials. Changing auth methods now works, and non-auth changes now succeed.connection upsertcreating a new connection with--source-namebut no--source-typesentsource.type: "", which the API rejects. It now sends WEBHOOK, matching the config it builds.connection upsertwith an inline source and no destination flags on an existing connection failed withmust contain at least one of [destination_id, destination]. It now keeps the stored destination, and the stored source in the reverse case.FetchSourceTypesread aSourceCreateRequestschema the spec no longer has, and cached the empty result. It now parsesSourceTypeConfig<TYPE>and never caches an empty parse.hookdeck/core. ONFLEET is the exception: it requires only a handshake, so its auth is treated as optional.auth_typeinference is documented in the help for the source and connection commands. That includes the case where a barewebhook_secret_keyis treated as Standard Webhooks.Follow-up fixes (from review)
Source auth built per source type. The auth flags (
--webhook-secret,--hmac-secret,--api-key, the basic auth flags) and the legacy--configkeys (webhook_secret,api_key,basic_auth,hmac) now buildconfig.authandauth_typefrom the source type's own methods in the spec, not one generic shape.--webhook-secretno longer overrides a provider's signature header. The API applies a source's storedheader_key,algorithmandencodingover the provider's defaults. The flag sentx-webhook-signature/sha256/hex for every type except STRIPE, so VAPI, FORMSTACK, BETTER_STACK, GRAFANA and SUPABASE sources rejected their provider's real requests. It now sends the secret alone, and adds the HMAC settings only where the method requires them: WEBHOOK and HTTP, which are unchanged.auth_typeis set for every type that offers a choice of method. GITLAB, GRAFANA, PROMETHEUS_ALERTMANAGER, BETTER_STACK and ORDINAL returned 422config.auth is not allowedwith the auth flags.--webhook-secreton PROMETHEUS_ALERTMANAGER, BETTER_STACK and ORDINAL used to get a 422.--api-keyon ORDINAL, GRAFANA, BETTER_STACK and ACUMATICA, which need their own header name, used to storex-api-key. Each error shows the--configform to use.Connections and destinations
connection upsertfails before any write when the destination differs, so it no longer creates an orphan destination.connection updatefails when--source-idor--destination-iddiffers. The MCPgateway_connections_writetool applies the same checks. Upsert with a different source still creates a separate connection, because connection names are unique per source.connection upsertlooks a connection up by exact name, and fails when several connections share the name and no source is given.connection upsert --rules '[]'clears the rules (Execution output, empty rules on upsert, and --rule-transform-name don't do what they say #472). An empty--rules-filedoes too, and dry-run says the rules will be cleared.destination updateandupsertwith--urlor--cli-pathbut no--typehave read-back acceptance tests (gateway destination update silently drops --url when --type is omitted #406). The fix was already in this PR.Testing for the follow-up:
go test ./...passes. Acceptance on the combined branch:connectionandconnection_update91 passed;source,connection_upsertanddestination143 passed; none skipped or failed. The live VAPI test checks that a request signed inx-signatureis verified and a wrong signature is not. Each fix was reverted in turn to confirm a test fails without it. REFERENCE.md is regenerated.Testing
pkg/cmdtests are kept offline by aTestMainthat serves the fixture.connection,sourceandconnection_upserttags. The fullsource(36),connection_upsert(38) andconnection(69) suites pass against the live API on the combined branch. The new gap tests fail against the pre-follow-up commit.go vet ./...,gofmtandgo run ./tools/generate-reference --checkare clean, andREFERENCE.mdis regenerated.golangci-lint. The installed binary was built with Go 1.25, and the repo targets 1.26.Notes for reviewers
--webhook-secreton PAYPAL, whose auth requireswebhook_id. The error points to the flag or--configshape to use..default('WEBHOOK')ontypein the API's source create schema. The CLI works around it, but it may be worth changing on the API side too.Generated by Claude Code