@jskit-ai/connectors-core 0.1.62 → 0.1.64

package/README.md

@@ -292,6 +292,10 @@ Provider `settingsFields[].authenticationMethods` restricts fields to particular
 credential modes; the shared parser rejects values left in an incompatible mode.
 
 Provider operations receive `(input, settings)` when constructing a request.
+An operation's `validateResult(result, request)` receives the parsed result and
+the request object its own `request` returned (`method`, `url`, `body`,
+`headers`), so it can confirm the provider returned the record, page or range
+that request asked for; a false return reports `connector_response_invalid`.
 OAuth providers may supply `oauth(settings)` to select regional authorization
 metadata. `oauthResource` may be a string or function of those settings; when
 present, it is sent as `resource` in consent, code exchange and refresh. The
@@ -392,8 +396,7 @@ the core and provider contracts are verified with controlled service-account fix
 ## File storage
 
 Import `createFileConnectionStore` and `createCredentialProtection` from
-`@jskit-ai/connectors-core/server/file-storage`. This entry point does not import
-or require database-runtime. Use `createFileConnectionStore({ directory,
+`@jskit-ai/connectors-core/server/file-storage`. Use `createFileConnectionStore({ directory,
 protection })` with an absolute private directory outside application source.
 Each connection uses an encrypted JSON record containing its grant and pending
 authorization attempts. The same protection contract is described below.
@@ -434,9 +437,8 @@ an old key before those rows are rewritten makes them unreadable. Applications
 with an existing vault can instead provide compatible `seal(value, binding)`
 and `open(ciphertext, binding)` methods.
 
-Install `@jskit-ai/database-runtime` explicitly when using the Knex store. It is
-an optional peer: editing portable configuration does not install or activate a
-database provider. Applications using another store do not need this peer.
+The Knex store uses the application's own Knex client and its `transaction()`;
+editing portable configuration does not install or activate a database provider.
 
 The package declares its authoritative migration directory in `package.json`.
 Use the normal app-owned `knexfile.js` and migration scripts described by the
@@ -551,3 +553,12 @@ authenticationMethod)` filters these choices; configuration validation uses the
 selected method. Forms remove incompatible scopes on method changes and select
 recommended method-specific scopes when entering that mode. Granola uses this
 to keep OAuth identity scopes out of API-key configuration.
+
+Provider `setup` holds the guide `url` and ordered `steps` shown to whoever
+configures the connection. `urlByAuthentication` and `stepsByAuthentication`
+override them for one authentication method; `urlForSettings(settings, method)`
+and `stepsForSettings(settings, method)` override both and return `undefined`
+to fall through. `getProviderSetup(provider, settings, method)` resolves that
+precedence into `{ url, steps }`. A provider with `configurationOnly`, or whose
+`configurationOnlyForSettings(settings)` returns true, has no account
+connection; `isProviderConfigurationOnly(provider, settings)` resolves both.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/connectors-core",
-  "version": "0.1.62",
+  "version": "0.1.64",
   "description": "Portable integration configuration and server-side account connection runtime.",
   "type": "module",
   "scripts": {
@@ -53,13 +53,7 @@
     }
   },
   "peerDependencies": {
-    "@jskit-ai/database-runtime": "0.1.245",
-    "@jskit-ai/http-runtime": "0.1.243",
-    "@jskit-ai/kernel": "0.1.245"
-  },
-  "peerDependenciesMeta": {
-    "@jskit-ai/database-runtime": {
-      "optional": true
-    }
+    "@jskit-ai/http-runtime": "0.1.245",
+    "@jskit-ai/kernel": "0.1.247"
   }
 }

package/src/server/connectionService.js

@@ -2,7 +2,7 @@ import * as oauth from "oauth4webapi";
 import { isDeepStrictEqual } from "node:util";
 import { createHash } from "node:crypto";
 import { createHttpClient } from "@jskit-ai/http-runtime/client";
-import { validateIntegrationConfiguration } from "../shared/configuration.js";
+import { registrationClientAuthentication, registrationGrantType, validateIntegrationConfiguration } from "../shared/configuration.js";
 import { ConnectorError, providerError } from "./errors.js";
 
 function publicConnection(connection) {
@@ -19,6 +19,24 @@ function publicConnection(connection) {
 }
 
 const ENV_SEEDED_MESSAGE = "This connection comes from an Env value; unlink or replace that value instead.";
+const VERIFICATION_SCOPE_MESSAGE = "Connection verification requires a permission absent from the application's configuration.";
+
+// An operation without scopes always runs; otherwise one of its scopes must be present.
+function requireOperationScope(operation, scopes, message) {
+  if (operation.scopes.length && !operation.scopes.some((scope) => scopes.includes(scope))) {
+    throw new ConnectorError("connector_scope_missing", message, { statusCode: 403 });
+  }
+}
+
+// Builds the provider request, reporting schema input errors as connector_input_invalid.
+function operationRequest(operation, input, settings, providerData) {
+  try { return operation.request(input, settings || {}, providerData); } catch (error) {
+    if (!error.fieldErrors) throw error;
+    const failure = new ConnectorError("connector_input_invalid", "Check the operation's input values.", { statusCode: 422 });
+    failure.fieldErrors = error.fieldErrors;
+    throw failure;
+  }
+}
 
 function validateCallbackUrl(value) {
   let url;
@@ -30,6 +48,29 @@ function validateCallbackUrl(value) {
   return url.href;
 }
 
+// Whether a stored connection still belongs to the configured integration and
+// OAuth client. `registration` is { registrationRef, clientId, grantType,
+// tokenEndpointAuthMethod } with defaults applied; only OAuth reads it.
+function connectionMatches(connection, integration, providerId, registration) {
+  const method = integration.authentication.method;
+  return connection.provider === providerId &&
+    (connection.method || "oauth2") === method &&
+    isDeepStrictEqual(connection.settings || {}, integration.settings || {}) &&
+    (!["api-key", "service-account"].includes(method) || connection.secretRef === integration.authentication.secretRef) &&
+    (method !== "service-account" || isDeepStrictEqual(connection.requestedScopes, integration.scopes)) &&
+    (method !== "oauth2" || (connection.registrationRef === registration.registrationRef &&
+      connection.clientId === registration.clientId &&
+      registrationGrantType(connection) === registration.grantType &&
+      (registration.grantType !== "client_credentials" || isDeepStrictEqual(connection.requestedScopes, integration.scopes)) &&
+      registrationClientAuthentication(connection) === registration.tokenEndpointAuthMethod));
+}
+
+// Providers that resend redirect_uri on refresh need the callback the grant was issued for.
+function callbackMatches(connection, provider, registration) {
+  return registration.grantType !== "authorization_code" || !provider.refreshRequiresRedirectUri ||
+    connection.callbackUrl === registration.callbackUrl;
+}
+
 function createConnectionService({
   configuration,
   providers,
@@ -105,8 +146,8 @@ function createConnectionService({
     if (registration.clientId.trim() === "MISSING") {
       throw new ConnectorError("connector_binding_missing", "The provider client ID is not configured.");
     }
-    const grantType = registration.grantType || "authorization_code";
-    const tokenEndpointAuthMethod = registration.tokenEndpointAuthMethod || "client_secret_post";
+    const grantType = registrationGrantType(registration);
+    const tokenEndpointAuthMethod = registrationClientAuthentication(registration);
     if (provider.oauthPkce === false && tokenEndpointAuthMethod === "none") {
       throw new ConnectorError("connector_mode_unavailable", "This provider's non-PKCE flow requires a confidential client.");
     }
@@ -235,11 +276,8 @@ function createConnectionService({
     if (integration.authentication.method !== "service-account" || typeof provider.serviceAccountGrant !== "function") {
       throw new ConnectorError("connector_mode_unavailable", "Select service-account credentials to verify this connection.");
     }
-    provider.operations[provider.checkOperation].request(verificationInput, integration.settings || {});
-    const required = provider.operations[provider.checkOperation].scopes;
-    if (required.length && !required.some((scope) => integration.scopes.includes(scope))) {
-      throw new ConnectorError("connector_scope_missing", "Connection verification requires a permission absent from the application's configuration.", { statusCode: 403 });
-    }
+    operationRequest(provider.operations[provider.checkOperation], verificationInput, integration.settings);
+    requireOperationScope(provider.operations[provider.checkOperation], integration.scopes, VERIFICATION_SCOPE_MESSAGE);
     return store.withConnection({ owner, integrationId }, async ({ save }) => {
       try {
         const binding = await serviceAccountCredentialFor(integration);
@@ -273,17 +311,11 @@ function createConnectionService({
     if (!operation || !Object.hasOwn(provider.operations, operationId)) {
       throw new ConnectorError("connector_operation_unknown", "This provider operation is not available.");
     }
-    if (["oauth2", "service-account"].includes(connection.method || "oauth2") && operation.scopes.length && !operation.scopes.some((scope) => connection.grantedScopes.includes(scope))) {
-      throw new ConnectorError("connector_scope_missing", "Connect again with the permission required for this operation.", { statusCode: 403 });
+    if (["oauth2", "service-account"].includes(connection.method || "oauth2")) {
+      requireOperationScope(operation, connection.grantedScopes, "Connect again with the permission required for this operation.");
     }
-    let request;
-    try { request = operation.request(input, connection.settings || {}, connection.providerData); } catch (error) {
-      if (!error.fieldErrors) throw error;
-      const failure = new ConnectorError("connector_input_invalid", "Check the operation's input values.", { statusCode: 422 });
-      failure.fieldErrors = error.fieldErrors;
-      throw failure;
-    }
-    const url = new URL(request.url);
+    const descriptor = operationRequest(operation, input, connection.settings, connection.providerData);
+    const url = new URL(descriptor.url);
     const origins = typeof provider.apiOrigins === "function" ? provider.apiOrigins(connection.settings || {}, connection.providerData) : provider.apiOrigins;
     if (url.protocol !== "https:" || url.username || url.password || !origins.includes(url.origin)) {
       throw new ConnectorError("connector_destination_invalid", "The provider operation has an invalid destination.");
@@ -300,17 +332,17 @@ function createConnectionService({
     if (connection.method === "api-key" && provider.apiKey.queryParameter) {
       url.searchParams.set(provider.apiKey.queryParameter, connection.apiKey);
     }
-    let body = request.body;
+    let body = descriptor.body;
     if (connection.method === "api-key" && provider.apiKey.bodyParameter) {
-      if (!body || typeof body !== "object" || Array.isArray(body) || ["GET", "HEAD"].includes(request.method)) {
+      if (!body || typeof body !== "object" || Array.isArray(body) || ["GET", "HEAD"].includes(descriptor.method)) {
         throw new ConnectorError("connector_request_invalid", "This provider requires a JSON request body.");
       }
       body = { ...body, [provider.apiKey.bodyParameter]: connection.apiKey };
     }
     const options = {
-      method: request.method,
+      method: descriptor.method,
       body,
-      headers: { ...request.headers, Accept: "application/json", ...(connection.method === "api-key"
+      headers: { ...descriptor.headers, Accept: "application/json", ...(connection.method === "api-key"
         ? provider.apiKey.headers?.(connection.apiKey, connection.settings || {})
         : connection.method === "none" ? {} : {
           ...provider.oauthHeaders?.({ clientId: connection.clientId }), Authorization: `Bearer ${connection.tokens.accessToken}`
@@ -329,7 +361,8 @@ function createConnectionService({
       options.signal.throwIfAborted();
       throw error;
     }
-    if (typeof operation.validateResult === "function" && !operation.validateResult(result)) {
+    // The validator also receives the operation's own request, so it can check the provider answered what was asked.
+    if (typeof operation.validateResult === "function" && !operation.validateResult(result, descriptor)) {
       throw new ConnectorError("connector_response_invalid", "The provider returned an unexpected response.", { statusCode: 502 });
     }
     return result;
@@ -364,10 +397,7 @@ function createConnectionService({
       throw new ConnectorError("connector_response_invalid", "The provider returned an invalid permission grant.", { statusCode: 502 });
     }
     connection.grantedScopes = connection.grantedScopes.filter((scope) => requestedScopes.includes(scope) && scopes.includes(scope));
-    const required = provider.operations[provider.checkOperation].scopes;
-    if (required.length && !required.some((scope) => connection.grantedScopes.includes(scope))) {
-      throw new ConnectorError("connector_scope_missing", "Connect again with the permission required for verification.", { statusCode: 403 });
-    }
+    requireOperationScope(provider.operations[provider.checkOperation], connection.grantedScopes, "Connect again with the permission required for verification.");
   }
 
   async function clientCredentialsGrant(registration, provider, settings, scopes, signal) {
@@ -392,11 +422,8 @@ function createConnectionService({
     if (registration.grantType !== "client_credentials") {
       throw new ConnectorError("connector_mode_unavailable", "Select client credentials to connect a service account.");
     }
-    provider.operations[provider.checkOperation].request(verificationInput, integration.settings || {});
-    const required = provider.operations[provider.checkOperation].scopes;
-    if (required.length && !required.some((scope) => integration.scopes.includes(scope))) {
-      throw new ConnectorError("connector_scope_missing", "Connection verification requires a permission absent from the application's configuration.", { statusCode: 403 });
-    }
+    operationRequest(provider.operations[provider.checkOperation], verificationInput, integration.settings);
+    requireOperationScope(provider.operations[provider.checkOperation], integration.scopes, VERIFICATION_SCOPE_MESSAGE);
     return store.withConnection({ owner, integrationId }, async ({ save }) => {
       try {
         const connection = {
@@ -419,7 +446,7 @@ function createConnectionService({
       throw new ConnectorError("connector_env_managed", ENV_SEEDED_MESSAGE, { statusCode: 409 });
     }
     // Resource-specific providers validate the first document ID before opening consent.
-    provider.operations[provider.checkOperation].request(verificationInput, integration.settings || {});
+    operationRequest(provider.operations[provider.checkOperation], verificationInput, integration.settings);
     const registration = await registrationFor(integration, provider);
     if (registration.grantType !== "authorization_code") {
       throw new ConnectorError("connector_mode_unavailable", "Service accounts connect without browser consent.");
@@ -494,8 +521,8 @@ function createConnectionService({
         if (!attempt || attempt.expiresAt <= now() || attempt.provider !== provider.id ||
           (attempt.codeVerifier === null) !== (provider.oauthPkce === false) ||
           attempt.clientId !== registration.client.client_id || attempt.registrationRef !== registration.registrationRef ||
-          (attempt.grantType || "authorization_code") !== registration.grantType ||
-          (attempt.tokenEndpointAuthMethod || "client_secret_post") !== registration.tokenEndpointAuthMethod ||
+          registrationGrantType(attempt) !== registration.grantType ||
+          registrationClientAuthentication(attempt) !== registration.tokenEndpointAuthMethod ||
           attempt.callbackUrl !== registration.callbackUrl || JSON.stringify(attempt.scopes) !== JSON.stringify(integration.scopes) ||
           !isDeepStrictEqual(attempt.settings || {}, integration.settings || {})) {
           throw new ConnectorError("connector_attempt_invalid", "The authorization attempt is invalid or has expired.");
@@ -545,10 +572,7 @@ function createConnectionService({
         !provider.apiKey?.bodyParameter && typeof provider.apiKey?.pathPrefix !== "function"))) {
       throw new ConnectorError("connector_mode_unavailable", "Select the matching credential mode to verify this connection.");
     }
-    const requiredScopes = provider.operations[provider.checkOperation].scopes;
-    if (requiredScopes.length && !requiredScopes.some((scope) => integration.scopes.includes(scope))) {
-      throw new ConnectorError("connector_scope_missing", "Connection verification requires a permission absent from the application's configuration.", { statusCode: 403 });
-    }
+    requireOperationScope(provider.operations[provider.checkOperation], integration.scopes, VERIFICATION_SCOPE_MESSAGE);
     return store.withConnection({ owner, integrationId }, async ({ save }) => {
       const connection = {
         integrationId, provider: provider.id, method,
@@ -575,9 +599,7 @@ function createConnectionService({
     if (!Object.hasOwn(provider.operations, operation)) {
       throw new ConnectorError("connector_operation_unknown", "This provider operation is not available.");
     }
-    if (provider.operations[operation].scopes.length && !provider.operations[operation].scopes.some((scope) => integration.scopes.includes(scope))) {
-      throw new ConnectorError("connector_scope_missing", "This operation requires a permission absent from the application's configuration.", { statusCode: 403 });
-    }
+    requireOperationScope(provider.operations[operation], integration.scopes, "This operation requires a permission absent from the application's configuration.");
     const usesApiKey = integration.authentication.method === "api-key";
     const usesServiceAccount = integration.authentication.method === "service-account";
     const usesOAuth = integration.authentication.method === "oauth2";
@@ -588,16 +610,9 @@ function createConnectionService({
         connection = envSeededConnection(integrationId, integration, provider, registration, seed);
         await save(connection);
       }
-      if (!connection || connection.status !== "connected" || connection.provider !== provider.id ||
-        (connection.method || "oauth2") !== integration.authentication.method ||
-        !isDeepStrictEqual(connection.settings || {}, integration.settings || {}) ||
-        ((usesApiKey || usesServiceAccount) && connection.secretRef !== integration.authentication.secretRef) ||
-        (usesServiceAccount && !isDeepStrictEqual(connection.requestedScopes, integration.scopes)) ||
-        (usesOAuth && (connection.registrationRef !== registration.registrationRef || connection.clientId !== registration.client.client_id ||
-            (connection.grantType || "authorization_code") !== registration.grantType ||
-            (registration.grantType === "client_credentials" && !isDeepStrictEqual(connection.requestedScopes, integration.scopes)) ||
-            (registration.grantType === "authorization_code" && provider.refreshRequiresRedirectUri && connection.callbackUrl !== registration.callbackUrl) ||
-            (connection.tokenEndpointAuthMethod || "client_secret_post") !== registration.tokenEndpointAuthMethod))) {
+      if (!connection || connection.status !== "connected" ||
+        !connectionMatches(connection, integration, provider.id, usesOAuth ? { ...registration, clientId: registration.client.client_id } : null) ||
+        (usesOAuth && !callbackMatches(connection, provider, registration))) {
         throw new ConnectorError("connector_reconnect_required", "Connect this account again.", { statusCode: 401 });
       }
       try {
@@ -655,17 +670,14 @@ function createConnectionService({
 
   async function status({ context, integrationId }) {
     const { owner, integration, provider } = await access(context, integrationId, "status");
+    // Compare against the configured registration without resolving its secrets.
     const registration = config.registrations[integration.authentication.registrationRef];
+    const configured = {
+      registrationRef: integration.authentication.registrationRef, clientId: registration?.clientId,
+      grantType: registrationGrantType(registration), tokenEndpointAuthMethod: registrationClientAuthentication(registration)
+    };
     return store.withConnection({ owner, integrationId }, async ({ connection }) => {
-      if (connection && !integration.authentication.refreshTokenRef && (connection.provider !== integration.provider ||
-        (connection.method || "oauth2") !== integration.authentication.method ||
-        !isDeepStrictEqual(connection.settings || {}, integration.settings || {}) ||
-        (["api-key", "service-account"].includes(integration.authentication.method) && connection.secretRef !== integration.authentication.secretRef) ||
-        (integration.authentication.method === "service-account" && !isDeepStrictEqual(connection.requestedScopes, integration.scopes)) ||
-        (integration.authentication.method === "oauth2" && (connection.registrationRef !== integration.authentication.registrationRef || connection.clientId !== registration?.clientId ||
-            (connection.grantType || "authorization_code") !== (registration?.grantType || "authorization_code") ||
-            (registration?.grantType === "client_credentials" && !isDeepStrictEqual(connection.requestedScopes, integration.scopes)) ||
-            (connection.tokenEndpointAuthMethod || "client_secret_post") !== (registration?.tokenEndpointAuthMethod || "client_secret_post"))))) {
+      if (connection && !integration.authentication.refreshTokenRef && !connectionMatches(connection, integration, integration.provider, configured)) {
         return publicConnection({ ...connection, status: "reconnect-required" });
       }
       let callbackUrl;
@@ -680,8 +692,7 @@ function createConnectionService({
               return { status: "connected", source: "env", provider: provider.id, integrationId, grantedScopes: [...integration.scopes], callbackUrl };
             }
           }
-          if (connection && provider.refreshRequiresRedirectUri && resolved.grantType === "authorization_code" &&
-              connection.callbackUrl !== resolved.callbackUrl) {
+          if (connection && !callbackMatches(connection, provider, resolved)) {
             return publicConnection({ ...connection, status: "reconnect-required" });
           }
         } else if (integration.authentication.method === "api-key") {

package/src/server/knexConnectionStore.js

@@ -1,5 +1,4 @@
 import { createHash } from "node:crypto";
-import { createWithTransaction } from "@jskit-ai/database-runtime/shared";
 
 const hash = (value) => createHash("sha256").update(value).digest("hex");
 
@@ -10,12 +9,10 @@ function createKnexConnectionStore({ knex, protection }) {
   if (typeof protection?.seal !== "function" || typeof protection?.open !== "function") {
     throw new TypeError("Connector storage requires credential protection.");
   }
-  const transaction = createWithTransaction(knex);
-
   async function withConnection({ owner, integrationId }, work) {
     const connectionKey = hash(JSON.stringify([owner.applicationId, owner.subjectId, integrationId]));
     const connectionBinding = `connection:${connectionKey}`;
-    return transaction(async (trx) => {
+    return knex.transaction(async (trx) => {
       // Retain this row on disconnect so other processes continue to lock the same identity.
       await trx("connector_connections").insert({ connection_key: connectionKey })
         .onConflict("connection_key").merge({ connection_key: connectionKey });

package/src/shared/configuration.js

@@ -54,6 +54,22 @@ class IntegrationConfigurationError extends Error {
   }
 }
 
+// Registrations, attempts and stored connections omit these when they use the defaults.
+const DEFAULT_GRANT_TYPE = "authorization_code";
+const DEFAULT_TOKEN_ENDPOINT_AUTH_METHOD = "client_secret_post";
+
+function registrationGrantType(record) {
+  return record?.grantType || DEFAULT_GRANT_TYPE;
+}
+
+function registrationClientAuthentication(record) {
+  return record?.tokenEndpointAuthMethod || DEFAULT_TOKEN_ENDPOINT_AUTH_METHOD;
+}
+
+function providerGrantTypes(provider) {
+  return provider.oauthGrantTypes || [DEFAULT_GRANT_TYPE];
+}
+
 function getProviderSettingsSchema(provider, settings = {}) {
   return typeof provider.settingsSchema === "function" ? provider.settingsSchema(settings) : provider.settingsSchema;
 }
@@ -66,15 +82,28 @@ function getProviderAccountModes(provider, settings = {}) {
   return provider.accountModesForSettings ? provider.accountModesForSettings(settings) : provider.accountModes;
 }
 
-function getProviderScopes(provider, settings = {}, grantType = "authorization_code", authenticationMethod) {
+function getProviderScopes(provider, settings = {}, grantType = DEFAULT_GRANT_TYPE, authenticationMethod) {
   const scopes = provider.scopesForGrantType ? provider.scopesForGrantType(grantType, settings)
     : provider.scopesForSettings ? provider.scopesForSettings(settings) : provider.scopes;
   return authenticationMethod ? scopes.filter(scope => !scope.authenticationMethods || scope.authenticationMethods.includes(authenticationMethod)) : scopes;
 }
 
-function getProviderClientAuthenticationMethods(provider, grantType = "authorization_code", settings = {}) {
+function getProviderClientAuthenticationMethods(provider, grantType = DEFAULT_GRANT_TYPE, settings = {}) {
   const methods = provider.oauthClientAuthenticationMethods;
-  return typeof methods === "function" ? methods(grantType, settings) : methods || ["client_secret_post"];
+  return typeof methods === "function" ? methods(grantType, settings) : methods || [DEFAULT_TOKEN_ENDPOINT_AUTH_METHOD];
+}
+
+// Setup text precedence: settings-dependent, then per-authentication-method, then static.
+function getProviderSetup(provider, settings = {}, authenticationMethod) {
+  const setup = provider.setup || {};
+  return {
+    url: setup.urlForSettings?.(settings, authenticationMethod) || setup.urlByAuthentication?.[authenticationMethod] || setup.url,
+    steps: setup.stepsForSettings?.(settings, authenticationMethod) || setup.stepsByAuthentication?.[authenticationMethod] || setup.steps
+  };
+}
+
+function isProviderConfigurationOnly(provider, settings = {}) {
+  return Boolean(provider.configurationOnly || provider.configurationOnlyForSettings?.(settings));
 }
 
 function validateIntegrationConfiguration(input, { providers = [], allowUnknownProviders = false } = {}) {
@@ -117,7 +146,7 @@ function validateIntegrationConfiguration(input, { providers = [], allowUnknownP
     const auth = integration.authentication;
     const provider = definitions.get(integration.provider);
     const registration = config.registrations[auth.registrationRef];
-    const grantType = registration?.grantType || "authorization_code";
+    const grantType = registrationGrantType(registration);
     if (auth.refreshTokenRef && auth.method !== "oauth2") {
       fieldErrors[`${path}.authentication.refreshTokenRef`] = "Only an OAuth connection can start from a refresh token.";
     }
@@ -181,11 +210,11 @@ function validateIntegrationConfiguration(input, { providers = [], allowUnknownP
       }
       if (auth.method === "oauth2" && registration?.source === "own") {
         const registrationPath = `registrations.${auth.registrationRef}`;
-        if (!(provider.oauthGrantTypes || ["authorization_code"]).includes(grantType)) {
+        if (!providerGrantTypes(provider).includes(grantType)) {
           fieldErrors[`${registrationPath}.grantType`] = "This provider does not support this OAuth flow.";
         }
         const methods = getProviderClientAuthenticationMethods(provider, grantType, integration.settings || {});
-        if (!methods.includes(registration.tokenEndpointAuthMethod || "client_secret_post")) {
+        if (!methods.includes(registrationClientAuthentication(registration))) {
           fieldErrors[`${registrationPath}.tokenEndpointAuthMethod`] = "This provider does not support this client authentication method.";
         }
         if (registration.clientId && provider.validateClientId) {
@@ -221,11 +250,18 @@ function parseIntegrationConfiguration(text, options) {
 }
 
 export {
+  DEFAULT_GRANT_TYPE,
+  DEFAULT_TOKEN_ENDPOINT_AUTH_METHOD,
+  registrationGrantType,
+  registrationClientAuthentication,
+  providerGrantTypes,
   getProviderAuthenticationMethods,
   getProviderClientAuthenticationMethods,
   getProviderAccountModes,
   getProviderScopes,
   getProviderSettingsSchema,
+  getProviderSetup,
+  isProviderConfigurationOnly,
   secretReference,
   integrationsSchema,
   IntegrationConfigurationError,

package/test/connectionService.test.js

@@ -79,6 +79,26 @@ test("credential-free grants require verification, authorize access and invalida
   assert.equal((await restart.status(input)).status, "disconnected");
 });
 
+test("result validation sees the request its operation built and rejects a mismatched answer", async () => {
+  const check = clickhouseProvider.operations["connection.check"];
+  const seen = [];
+  let expectedUser = "default";
+  const provider = { ...clickhouseProvider, operations: { ...clickhouseProvider.operations, "connection.check": { ...check,
+    validateResult: (value, request) => { seen.push(request); return check.validateResult(value) && value.data[0].user === expectedUser; } } } };
+  const service = createConnectionService({
+    configuration: databaseConfiguration({ method: "none" }), providers: [provider], store: memoryStore(),
+    authorize: async (context) => context, resolveReference: async () => "secret",
+    fetchImpl: async () => Response.json({ meta: [], data: [{ ok: 1, user: "default" }], rows: 1 })
+  });
+  const input = { context: owner, integrationId: "database" };
+  await service.connectWithoutCredentials(input);
+  const built = check.request({}, { httpUrl: "https://database.example:8443/" });
+  assert.equal(seen[0].url, built.url);
+  assert.equal(seen[0].method, built.method);
+  expectedUser = "someone-else";
+  await assert.rejects(service.invoke({ ...input, operation: "connection.check" }), { code: "connector_response_invalid", statusCode: 502 });
+});
+
 test("the ordinary credential-free Feature action verifies without resolving references", async () => {
   const contexts = [];
   let actions;
@@ -735,6 +755,16 @@ test("invalid operation input remains a field error and never reaches the provid
     return true;
   });
   assert.equal(requests.length, count);
+  // Preflight verification input reports the same field error before consent opens.
+  await assert.rejects(service.beginAuthorization({
+    context: owner, integrationId: "calendar", verificationInput: { maxResults: -1 }
+  }), (error) => {
+    assert.equal(error.code, "connector_input_invalid");
+    assert.equal(error.statusCode, 422);
+    assert.ok(error.fieldErrors.maxResults);
+    return true;
+  });
+  assert.equal(requests.length, count);
 });
 
 test("saved grants cannot override permissions removed from application source", async () => {

package/test/providerSetup.test.js

@@ -0,0 +1,28 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { getProviderSetup, isProviderConfigurationOnly } from "../src/shared/configuration.js";
+
+const provider = {
+  configurationOnlyForSettings: (settings) => settings.mode === "public",
+  setup: {
+    url: "https://example.test/token", steps: ["Create a token."],
+    urlByAuthentication: { oauth2: "https://example.test/oauth" }, stepsByAuthentication: { oauth2: ["Register a client."] },
+    urlForSettings: (settings) => settings.mode === "mcp" ? "https://example.test/mcp" : undefined,
+    stepsForSettings: (settings, method) => settings.mode === "mcp" ? [`Register an MCP client for ${method}.`] : undefined
+  }
+};
+
+test("provider setup resolves settings, then authentication method, then static text", () => {
+  assert.deepEqual(getProviderSetup(provider, {}, "api-key"), { url: "https://example.test/token", steps: ["Create a token."] });
+  assert.deepEqual(getProviderSetup(provider, {}, "oauth2"), { url: "https://example.test/oauth", steps: ["Register a client."] });
+  assert.deepEqual(getProviderSetup(provider, { mode: "mcp" }, "oauth2"),
+    { url: "https://example.test/mcp", steps: ["Register an MCP client for oauth2."] });
+  assert.deepEqual(getProviderSetup({ setup: { url: "https://example.test", steps: [] } }),
+    { url: "https://example.test", steps: [] });
+});
+
+test("configuration-only providers resolve static and settings-dependent flags", () => {
+  assert.equal(isProviderConfigurationOnly({ configurationOnly: true }), true);
+  assert.equal(isProviderConfigurationOnly(provider, { mode: "public" }), true);
+  assert.equal(isProviderConfigurationOnly(provider, {}), false);
+});