@jskit-ai/connectors-core 0.1.61 → 0.1.63

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.61",
+  "version": "0.1.63",
   "description": "Portable integration configuration and server-side account connection runtime.",
   "type": "module",
   "scripts": {
@@ -53,13 +53,7 @@
     }
   },
   "peerDependencies": {
-    "@jskit-ai/database-runtime": "0.1.244",
-    "@jskit-ai/http-runtime": "0.1.242",
-    "@jskit-ai/kernel": "0.1.244"
-  },
-  "peerDependenciesMeta": {
-    "@jskit-ai/database-runtime": {
-      "optional": true
-    }
+    "@jskit-ai/http-runtime": "0.1.244",
+    "@jskit-ai/kernel": "0.1.246"
   }
 }

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) {
@@ -13,10 +13,31 @@ function publicConnection(connection) {
     integrationId: connection.integrationId,
     grantedScopes: [...connection.grantedScopes],
     verifiedAt: connection.verifiedAt,
-    ...(connection.accountLabel ? { accountLabel: connection.accountLabel } : {})
+    ...(connection.accountLabel ? { accountLabel: connection.accountLabel } : {}),
+    ...(connection.source ? { source: connection.source } : {})
   };
 }
 
+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;
   try { url = new URL(value); } catch { /* reported below */ }
@@ -27,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,
@@ -102,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.");
     }
@@ -166,6 +210,38 @@ function createConnectionService({
     }
   }
 
+  // An Env refresh token seeds the shared connection; the app then refreshes
+  // and stores rotated tokens itself, and reseeds when the value or the OAuth
+  // client changes.
+  async function envRefreshTokenFor(integration) {
+    try {
+      const value = await resolveReference(integration.authentication.refreshTokenRef);
+      const refreshToken = typeof value === "string" ? value.trim() : "";
+      if (!refreshToken || refreshToken === "MISSING" || /\s/u.test(refreshToken)) throw new Error("Invalid token.");
+      return { refreshToken, fingerprint: createHash("sha256").update(refreshToken).digest("hex") };
+    } catch {
+      throw new ConnectorError("connector_binding_missing", "The refresh token binding is missing or invalid.");
+    }
+  }
+
+  function envSeedIsCurrent(connection, seed, registration) {
+    return connection?.seedFingerprint === seed.fingerprint && connection.clientId === registration.client.client_id &&
+      connection.registrationRef === registration.registrationRef &&
+      connection.tokenEndpointAuthMethod === registration.tokenEndpointAuthMethod;
+  }
+
+  function envSeededConnection(integrationId, integration, provider, registration, seed) {
+    return {
+      integrationId, provider: provider.id, registrationRef: registration.registrationRef,
+      grantType: registration.grantType, clientId: registration.client.client_id,
+      tokenEndpointAuthMethod: registration.tokenEndpointAuthMethod, status: "connected", source: "env",
+      seedFingerprint: seed.fingerprint, verifiedAt: now(), settings: structuredClone(integration.settings || {}),
+      ...(provider.refreshRequiresRedirectUri ? { callbackUrl: registration.callbackUrl } : {}),
+      tokens: { accessToken: null, refreshToken: seed.refreshToken, expiresAt: 0 },
+      grantedScopes: [...integration.scopes]
+    };
+  }
+
   async function serviceAccountGrant(integration, provider, binding, signal) {
     if (typeof provider.serviceAccountGrant !== "function") {
       throw new ConnectorError("connector_mode_unavailable", "This provider does not implement service-account authorization.");
@@ -200,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);
@@ -238,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.");
@@ -265,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}`
@@ -294,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;
@@ -329,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) {
@@ -357,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 = {
@@ -380,8 +442,11 @@ function createConnectionService({
 
   async function beginAuthorization({ context, integrationId, verificationInput = {}, signal }) {
     const { owner, integration, provider } = await access(context, integrationId, "connect");
+    if (integration.authentication.refreshTokenRef) {
+      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.");
@@ -456,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.");
@@ -507,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,
@@ -537,24 +599,20 @@ 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";
     const registration = usesOAuth ? await registrationFor(integration, provider) : null;
+    const seed = integration.authentication.refreshTokenRef ? await envRefreshTokenFor(integration) : null;
     const outcome = await store.withConnection({ owner, integrationId }, async ({ connection, save }) => {
-      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 (seed && !envSeedIsCurrent(connection, seed, registration)) {
+        connection = envSeededConnection(integrationId, integration, provider, registration, seed);
+        await save(connection);
+      }
+      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 {
@@ -597,8 +655,11 @@ function createConnectionService({
         });
         return { result };
       } catch (error) {
-        const failure = providerError(error);
-        if (failure.code === "connector_reconnect_required") await save({ ...connection, status: "reconnect-required" });
+        let failure = providerError(error);
+        if (failure.code === "connector_reconnect_required") {
+          await save({ ...connection, status: "reconnect-required" });
+          if (seed) failure = new ConnectorError(failure.code, "The refresh token in Env no longer works; replace that Env value.", { statusCode: 401 });
+        }
         // Commit rotated tokens and reconnect state even when the API request fails.
         return { failure };
       }
@@ -609,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 && (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;
@@ -627,8 +685,14 @@ function createConnectionService({
         if (integration.authentication.method === "oauth2") {
           const resolved = await registrationFor(integration, provider);
           callbackUrl = resolved.callbackUrl;
-          if (connection && provider.refreshRequiresRedirectUri && resolved.grantType === "authorization_code" &&
-              connection.callbackUrl !== resolved.callbackUrl) {
+          if (integration.authentication.refreshTokenRef) {
+            const seed = await envRefreshTokenFor(integration);
+            // A new value is used on the next call; until then it reads as connected from Env.
+            if (!envSeedIsCurrent(connection, seed, resolved)) {
+              return { status: "connected", source: "env", provider: provider.id, integrationId, grantedScopes: [...integration.scopes], callbackUrl };
+            }
+          }
+          if (connection && !callbackMatches(connection, provider, resolved)) {
             return publicConnection({ ...connection, status: "reconnect-required" });
           }
         } else if (integration.authentication.method === "api-key") {
@@ -647,7 +711,10 @@ function createConnectionService({
   }
 
   async function disconnect({ context, integrationId }) {
-    const { owner } = await access(context, integrationId, "disconnect");
+    const { owner, integration } = await access(context, integrationId, "disconnect");
+    if (integration.authentication.refreshTokenRef) {
+      throw new ConnectorError("connector_env_managed", ENV_SEEDED_MESSAGE, { statusCode: 409 });
+    }
     await store.withConnection({ owner, integrationId }, async ({ remove }) => remove());
     return { status: "disconnected" };
   }

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

@@ -9,7 +9,8 @@ const secretReference = {
 const authenticationSchema = createSchema({
   method: { ...name, enum: ["oauth2", "api-key", "service-account", "none"] },
   registrationRef: { ...name, required: false },
-  secretRef: { ...secretReference, required: false }
+  secretRef: { ...secretReference, required: false },
+  refreshTokenRef: { ...secretReference, required: false }
 });
 const assistantPermission = { type: "string", enum: ["ask", "always", "never"] };
 const assistantPolicySchema = createSchema({
@@ -53,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;
 }
@@ -65,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 } = {}) {
@@ -116,12 +146,20 @@ 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.";
+    }
     if (auth.method === "oauth2") {
       if (!auth.registrationRef || !Object.hasOwn(config.registrations, auth.registrationRef)) {
         fieldErrors[`${path}.authentication.registrationRef`] = "Select a registration defined in this file.";
       }
       if (auth.secretRef) fieldErrors[`${path}.authentication.secretRef`] = "Use the registration's secret reference.";
+      if (auth.refreshTokenRef && integration.accountMode !== "shared") {
+        fieldErrors[`${path}.authentication.refreshTokenRef`] = "Only a shared connection can start from a refresh token in Env.";
+      } else if (auth.refreshTokenRef && grantType !== "authorization_code") {
+        fieldErrors[`${path}.authentication.refreshTokenRef`] = "Client credentials do not use a refresh token.";
+      }
       if (grantType === "client_credentials" && integration.accountMode === "per-user") {
         fieldErrors[`${path}.accountMode`] = "A service account cannot connect as each app user.";
       }
@@ -172,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) {
@@ -212,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);
+});

package/test/refreshTokenSeed.test.js

@@ -0,0 +1,152 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { googleCalendarProvider } from "../../connector-google-calendar/src/server/provider.js";
+import { createConnectionService, createEnvironmentReferenceResolver } from "../src/server/index.js";
+import { validateIntegrationConfiguration } from "../src/shared/configuration.js";
+
+const listScope = "https://www.googleapis.com/auth/calendar.calendarlist.readonly";
+const owner = { applicationId: "app-1", subjectId: "app" };
+const integrationId = "calendar";
+
+function configuration({ accountMode = "shared", method = "oauth2", refreshTokenRef = "env:GOOGLE_REFRESH_TOKEN", grantType } = {}) {
+  return {
+    schemaVersion: 1,
+    integrations: {
+      calendar: {
+        provider: "google-calendar", accountMode, scopes: [listScope],
+        authentication: method === "oauth2"
+          ? { method, registrationRef: "google", ...(refreshTokenRef ? { refreshTokenRef } : {}) }
+          : { method, secretRef: "env:KEY", refreshTokenRef },
+        settings: {}
+      }
+    },
+    registrations: {
+      google: {
+        source: "own", clientId: "client-1", clientSecretRef: "env:GOOGLE_SECRET",
+        ...(grantType ? { grantType, tokenEndpointAuthMethod: "client_secret_basic" } : { callbackUrlRef: "env:CALLBACK" })
+      }
+    }
+  };
+}
+
+function memoryStore() {
+  const connections = new Map();
+  return {
+    connections,
+    async withConnection({ integrationId: id }, run) {
+      let pending = structuredClone(connections.get(id) || null);
+      const result = await run({
+        connection: pending,
+        save: async (value) => { pending = structuredClone(value); },
+        remove: async () => { pending = null; },
+        putAttempt: async () => {},
+        consumeAttempt: async () => null
+      });
+      if (pending) connections.set(id, pending);
+      else connections.delete(id);
+      return result;
+    }
+  };
+}
+
+function setup({ env = { GOOGLE_REFRESH_TOKEN: "seed-token-1" } } = {}) {
+  const variables = { GOOGLE_SECRET: "client-secret", CALLBACK: "http://127.0.0.1:8080/callback", ...env };
+  const store = memoryStore();
+  const refreshes = [];
+  const revoked = new Set();
+  let time = 1_000_000;
+  const service = createConnectionService({
+    configuration: configuration(),
+    providers: [googleCalendarProvider],
+    store,
+    authorize: async (context) => context,
+    resolveReference: createEnvironmentReferenceResolver(variables),
+    now: () => time,
+    async fetchImpl(url, init) {
+      if (String(url) === "https://oauth2.googleapis.com/token") {
+        const body = new URLSearchParams(init.body);
+        const refreshToken = body.get("refresh_token");
+        refreshes.push(refreshToken);
+        if (revoked.has(refreshToken)) return Response.json({ error: "invalid_grant" }, { status: 400 });
+        return Response.json({
+          token_type: "Bearer", access_token: `access-${refreshes.length}`, refresh_token: `rotated-${refreshes.length}`,
+          expires_in: 3600, scope: listScope
+        });
+      }
+      return Response.json({ kind: "calendar#calendarList", items: [] });
+    }
+  });
+  const call = () => service.invoke({ context: owner, integrationId, operation: googleCalendarProvider.checkOperation });
+  return { service, store, variables, refreshes, revoked, call, advance: (ms) => { time += ms; } };
+}
+
+test("refreshTokenRef is accepted only on a shared OAuth integration with a browser registration", () => {
+  const validate = (config) => validateIntegrationConfiguration(config, { providers: [googleCalendarProvider] });
+  assert.equal(validate(configuration()).integrations.calendar.authentication.refreshTokenRef, "env:GOOGLE_REFRESH_TOKEN");
+  const refused = [
+    [configuration({ accountMode: "per-user" }), "Only a shared connection can start from a refresh token in Env."],
+    [configuration({ grantType: "client_credentials" }), "Client credentials do not use a refresh token."],
+    [configuration({ method: "api-key" }), "Only an OAuth connection can start from a refresh token."]
+  ];
+  for (const [config, message] of refused) {
+    assert.throws(() => validate(config), (error) => error.fieldErrors["integrations.calendar.authentication.refreshTokenRef"] === message);
+  }
+  assert.throws(() => validate(configuration({ refreshTokenRef: "a-raw-token" })), { code: "integration_configuration_invalid" });
+});
+
+test("the Env refresh token seeds the shared connection, which then refreshes on its own", async () => {
+  const { service, store, refreshes, call, advance } = setup();
+  assert.deepEqual(await service.status({ context: owner, integrationId }), {
+    status: "connected", source: "env", provider: "google-calendar", integrationId, grantedScopes: [listScope],
+    callbackUrl: "http://127.0.0.1:8080/callback"
+  });
+
+  await call();
+  assert.deepEqual(refreshes, ["seed-token-1"]);
+  const stored = store.connections.get(integrationId);
+  assert.equal(stored.source, "env");
+  assert.equal(stored.tokens.refreshToken, "rotated-1");
+  assert.equal(JSON.stringify(stored).includes("seed-token-1"), false, "the seed itself is not kept once rotated");
+  assert.equal((await service.status({ context: owner, integrationId })).source, "env");
+
+  await call();
+  assert.deepEqual(refreshes, ["seed-token-1"], "a valid access token is reused");
+  advance(3600 * 1000);
+  await call();
+  assert.deepEqual(refreshes, ["seed-token-1", "rotated-1"], "the rotated token renews, not the seed");
+});
+
+test("a replaced Env value reseeds on the next call", async () => {
+  const { variables, refreshes, call } = setup();
+  await call();
+  variables.GOOGLE_REFRESH_TOKEN = "seed-token-2";
+  await call();
+  assert.deepEqual(refreshes, ["seed-token-1", "seed-token-2"]);
+});
+
+test("a revoked Env token asks for a new value, and a new value recovers", async () => {
+  const { service, variables, revoked, call } = setup();
+  revoked.add("seed-token-1");
+  await assert.rejects(call(), {
+    code: "connector_reconnect_required",
+    message: "The refresh token in Env no longer works; replace that Env value."
+  });
+  assert.equal((await service.status({ context: owner, integrationId })).status, "reconnect-required");
+  variables.GOOGLE_REFRESH_TOKEN = "seed-token-2";
+  assert.equal((await service.status({ context: owner, integrationId })).status, "connected");
+  await call();
+});
+
+test("an Env-seeded connection is not disconnected or reconnected in the app", async () => {
+  const { service, call } = setup();
+  await call();
+  const envManaged = { code: "connector_env_managed", statusCode: 409, message: "This connection comes from an Env value; unlink or replace that value instead." };
+  await assert.rejects(service.disconnect({ context: owner, integrationId }), envManaged);
+  await assert.rejects(service.beginAuthorization({ context: owner, integrationId }), envManaged);
+});
+
+test("a missing Env value reads as unconfigured", async () => {
+  const { service, call } = setup({ env: {} });
+  assert.deepEqual(await service.status({ context: owner, integrationId }), { status: "unconfigured", configurationError: "connector_binding_missing" });
+  await assert.rejects(call(), { code: "connector_binding_missing" });
+});