@jskit-ai/connectors-core 0.2.2 → 0.2.4

package/src/server/credentialProtection.js

@@ -1,33 +1,44 @@
 import { CompactEncrypt, compactDecrypt } from "jose";
 import { ConnectorError } from "./errors.js";
 
+/**
+ * Seals values with the active key and opens them with any named key, each bound to its record.
+ * @param {object} options
+ * @param {Record<string, Uint8Array>} options.keys Named 32-byte keys.
+ * @param {string} options.activeKeyId The key that seals new values.
+ */
 function createCredentialProtection({ keys, activeKeyId }) {
-  const keyring = new Map(Object.entries(keys || {}));
+  const keyring = new Map(Object.entries(keys));
   if (!keyring.has(activeKeyId) || [...keyring.values()].some((key) => !(key instanceof Uint8Array) || key.length !== 32)) {
     throw new TypeError("Credential protection requires named 32-byte keys and an active key ID.");
   }
   const encoder = new TextEncoder();
   const decoder = new TextDecoder();
-  return Object.freeze({
-    async seal(value, binding) {
-      return new CompactEncrypt(encoder.encode(JSON.stringify({ binding, value })))
-        .setProtectedHeader({ alg: "dir", enc: "A256GCM", kid: activeKeyId })
-        .encrypt(keyring.get(activeKeyId));
-    },
-    async open(ciphertext, binding) {
-      try {
-        const { plaintext } = await compactDecrypt(ciphertext, (header) => {
-          const key = keyring.get(header.kid);
-          if (!key) throw new Error("Unknown key.");
-          return key;
-        }, { keyManagementAlgorithms: ["dir"], contentEncryptionAlgorithms: ["A256GCM"] });
-        const envelope = JSON.parse(decoder.decode(plaintext));
-        if (envelope.binding !== binding) throw new Error("Incorrect record binding.");
-        return envelope.value;
-      } catch {
-        throw new ConnectorError("connector_credentials_unavailable", "Stored credentials could not be opened.", { statusCode: 500 });
-      }
+
+  async function seal(value, binding) {
+    return new CompactEncrypt(encoder.encode(JSON.stringify({ binding, value })))
+      .setProtectedHeader({ alg: "dir", enc: "A256GCM", kid: activeKeyId })
+      .encrypt(keyring.get(activeKeyId));
+  }
+
+  async function open(ciphertext, binding) {
+    try {
+      const { plaintext } = await compactDecrypt(ciphertext, (header) => {
+        const key = keyring.get(header.kid);
+        if (!key) throw new Error("Unknown key.");
+        return key;
+      }, { keyManagementAlgorithms: ["dir"], contentEncryptionAlgorithms: ["A256GCM"] });
+      const envelope = JSON.parse(decoder.decode(plaintext));
+      if (envelope.binding !== binding) throw new Error("Incorrect record binding.");
+      return envelope.value;
+    } catch {
+      throw new ConnectorError("connector_credentials_unavailable", "Stored credentials could not be opened.", { statusCode: 500 });
     }
+  }
+
+  return Object.freeze({
+    seal,
+    open
   });
 }
 

package/src/server/environmentReferences.js

@@ -1,6 +1,15 @@
 import { ConnectorError } from "./errors.js";
 
-function createEnvironmentReferenceResolver(env = process.env) {
+/**
+ * Resolves `env:NAME` references from the application's environment; an
+ * absent, blank or MISSING value is a missing binding.
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} env The application's environment, such as `process.env`.
+ * @returns {import("./types.js").ResolveReference}
+ */
+function createEnvironmentReferenceResolver(env) {
+  if (!env) {
+    throw new TypeError("createEnvironmentReferenceResolver requires the application's environment, such as process.env.");
+  }
   return async (reference) => {
     const match = /^env:([A-Z_][A-Z0-9_]*)$/u.exec(reference);
     if (!match || typeof env[match[1]] !== "string" || (!env[match[1]].trim() || env[match[1]].trim() === "MISSING")) {

package/src/server/errors.js

@@ -2,6 +2,15 @@
 // so each sentence also has a messageCode (with messageParams) that renders it from
 // the "jskit.<messageCode>" catalog entry; message stays that English text.
 class ConnectorError extends Error {
+  /**
+   * @param {string} code
+   * @param {string} message
+   * @param {object} [details]
+   * @param {number} [details.statusCode]
+   * @param {number} [details.retryAfterSeconds]
+   * @param {string} [details.messageCode]
+   * @param {Record<string, unknown>} [details.messageParams]
+   */
   constructor(code, message, { statusCode = 400, retryAfterSeconds, messageCode, messageParams } = {}) {
     super(message);
     this.name = "ConnectorError";
@@ -15,20 +24,31 @@ class ConnectorError extends Error {
   }
 }
 
+/**
+ * The refusal for a provider's failed HTTP response, by its status, without the
+ * provider's own text: what a provider's exchange() throws for a response it
+ * does not map itself.
+ * @param {number} status
+ */
+function providerStatusError(status) {
+  if (status === 401) {
+    return new ConnectorError("connector_reconnect_required", "Connect this account again.", { statusCode: 401, messageCode: "connectors.connection.connectAccountAgain" });
+  }
+  if (status === 403) return new ConnectorError("connector_permission_denied", "The provider denied this operation.", { statusCode: 403, messageCode: "connectors.connection.providerDeniedOperation" });
+  if (status === 429) return new ConnectorError("connector_rate_limited", "The provider's request limit was reached.", { statusCode: 429, messageCode: "connectors.connection.providerRequestLimitReached" });
+  return new ConnectorError("connector_provider_failed", "The provider request failed. Try again.", { statusCode: 502, messageCode: "connectors.connection.providerRequestFailedTryAgain" });
+}
+
 function providerError(error) {
   if (error instanceof ConnectorError) return error;
   const status = Number(error?.status || error?.statusCode || 0);
   if (error?.name === "AbortError") return new ConnectorError("connector_cancelled", "The operation was cancelled.", { messageCode: "connectors.connection.operationCancelled" });
   if (error?.name === "TimeoutError") return new ConnectorError("connector_provider_timeout", "The provider request timed out. Try again.", { statusCode: 504 });
-  if (["invalid_grant", "invalid_client"].includes(error?.error) || status === 401) {
-    return new ConnectorError("connector_reconnect_required", "Connect this account again.", { statusCode: 401, messageCode: "connectors.connection.connectAccountAgain" });
-  }
+  if (["invalid_grant", "invalid_client"].includes(error?.error) || status === 401) return providerStatusError(401);
   if (["access_denied", "user_cancelled_login", "user_cancelled_authorize"].includes(error?.error)) {
     return new ConnectorError("connector_consent_denied", "Account access was declined.");
   }
-  if (status === 403) return new ConnectorError("connector_permission_denied", "The provider denied this operation.", { statusCode: 403, messageCode: "connectors.connection.providerDeniedOperation" });
-  if (status === 429) return new ConnectorError("connector_rate_limited", "The provider's request limit was reached.", { statusCode: 429, messageCode: "connectors.connection.providerRequestLimitReached" });
-  return new ConnectorError("connector_provider_failed", "The provider request failed. Try again.", { statusCode: 502, messageCode: "connectors.connection.providerRequestFailedTryAgain" });
+  return providerStatusError(status);
 }
 
-export { ConnectorError, providerError };
+export { ConnectorError, providerError, providerStatusError };

package/src/server/fileConnectionStore.js

@@ -5,8 +5,18 @@ import path from "node:path";
 import lockfile from "proper-lockfile";
 import { ConnectorError } from "./errors.js";
 
+/**
+ * Connections kept as encrypted JSON files in a private directory, one locked file per connection.
+ * @param {object} options
+ * @param {string} options.directory An absolute private runtime directory.
+ * @param {import("./types.js").CredentialProtection} options.protection
+ * @param {number} [options.directoryMode]
+ * @param {number} [options.fileMode]
+ * @param {() => number} [options.now]
+ */
 function createFileConnectionStore({ directory, protection, directoryMode = 0o700, fileMode = 0o600, now = Date.now }) {
   if (typeof directory !== "string" || !path.isAbsolute(directory)) throw new TypeError("Use an absolute private runtime directory.");
+  // readable-check: allow method-probe - input validation: the application passes its credential protection
   if (typeof protection?.seal !== "function" || typeof protection?.open !== "function") throw new TypeError("Credential protection is required.");
   const root = path.resolve(directory);
   const storageError = () => new ConnectorError("connector_storage_invalid", "Connection state could not be read safely.", { statusCode: 500 });

package/src/server/index.js

@@ -1,4 +1,4 @@
 export { createConnectionService } from "./connectionService.js";
 export { createEnvironmentReferenceResolver } from "./environmentReferences.js";
-export { ConnectorError } from "./errors.js";
+export { ConnectorError, providerStatusError } from "./errors.js";
 export { createConnectorsFeature } from "./ConnectorsFeature.js";

package/src/server/knexConnectionStore.js

@@ -2,10 +2,18 @@ import { createHash } from "node:crypto";
 
 const hash = (value) => createHash("sha256").update(value).digest("hex");
 
+/**
+ * Connections kept encrypted in the connector tables, each locked in a transaction while it is used.
+ * @param {object} options
+ * @param {import("@jskit-ai/database-runtime/server/types").RuntimeKnex} options.knex The application's transactional Knex client.
+ * @param {import("./types.js").CredentialProtection} options.protection
+ */
 function createKnexConnectionStore({ knex, protection }) {
+  // readable-check: allow method-probe - input validation: the application passes its own Knex instance
   if (typeof knex !== "function" || typeof knex.transaction !== "function") {
-    throw new TypeError("Connector storage requires the application's transactional Knex client.");
+    throw new TypeError("createKnexConnectionStore requires the application's Knex instance.");
   }
+  // readable-check: allow method-probe - input validation: the application passes its credential protection
   if (typeof protection?.seal !== "function" || typeof protection?.open !== "function") {
     throw new TypeError("Connector storage requires credential protection.");
   }
@@ -56,7 +64,10 @@ function createKnexConnectionStore({ knex, protection }) {
     return knex("connector_authorization_attempts").where("expires_at", "<=", before).delete();
   }
 
-  return Object.freeze({ withConnection, pruneExpiredAttempts });
+  return Object.freeze({
+    withConnection,
+    pruneExpiredAttempts
+  });
 }
 
 export { createKnexConnectionStore };

package/src/server/providerRequests.js

@@ -0,0 +1,291 @@
+import * as oauth from "oauth4webapi";
+import { createHttpClient } from "@jskit-ai/http-runtime/client";
+import { ConnectorError } from "./errors.js";
+
+const DEFAULT_SCOPE_SEPARATOR = " ";
+// Every OAuth token request takes this timeout; a provider's operations default to it.
+const REQUEST_TIMEOUT_MS = 15_000;
+const DEFAULT_TOKEN_REFRESH_LEEWAY_MS = 30_000;
+
+/**
+ * A provider as an integration's requests use it: with its runtime for the
+ * integration's settings, its checkOperation for the credential mode and its
+ * defaults applied.
+ * @typedef {import("./types.js").ConnectorProvider & { checkOperation: string, scopeSeparator: string, requestTimeoutMs: number, tokenRefreshLeewayMs: number }} ConnectionProvider
+ */
+
+/**
+ * @param {import("./types.js").ConnectorProvider} definition
+ * @param {{ settings: Record<string, any>, authentication: { method: string } }} integration
+ * @returns {ConnectionProvider}
+ */
+function connectionProvider(definition, integration) {
+  // readable-check: allow method-probe - optional operation: runtimeForSettings is an optional hook of the provider definition
+  const runtime = typeof definition.runtimeForSettings === "function" ? { ...definition, ...definition.runtimeForSettings(integration.settings) } : definition;
+  return {
+    ...runtime,
+    // readable-check: allow method-probe - data: a provider definition gives checkOperation as an operation id or as a function of the credential mode
+    checkOperation: typeof runtime.checkOperation === "function" ? runtime.checkOperation(integration.authentication.method) : runtime.checkOperation,
+    scopeSeparator: runtime.scopeSeparator || DEFAULT_SCOPE_SEPARATOR,
+    requestTimeoutMs: runtime.requestTimeoutMs ?? REQUEST_TIMEOUT_MS,
+    tokenRefreshLeewayMs: runtime.tokenRefreshLeewayMs ?? DEFAULT_TOKEN_REFRESH_LEEWAY_MS
+  };
+}
+
+// An operation without scopes always runs; otherwise one of its scopes must be present.
+function requireOperationScope(operation, scopes, message, { messageCode }) {
+  if (operation.scopes.length && !operation.scopes.some((scope) => scopes.includes(scope))) {
+    throw new ConnectorError("connector_scope_missing", message, { statusCode: 403, messageCode });
+  }
+}
+
+// The token response oauth4webapi processes, rewritten by the provider's normalizeTokenResponse() when it has one.
+function tokenResponse(provider, response, details) {
+  // readable-check: allow method-probe - optional operation: normalizeTokenResponse is an optional hook of the provider definition
+  return typeof provider.normalizeTokenResponse === "function" ? provider.normalizeTokenResponse(response, details) : response;
+}
+
+// The headers that carry a connection's credential: the provider's API-key headers, or its OAuth headers and bearer token.
+function credentialHeaders(provider, connection, settings) {
+  if (connection.method === "none") return {};
+  if (connection.method === "api-key") {
+    // readable-check: allow method-probe - optional operation: apiKey.headers is an optional hook of the provider definition
+    return typeof provider.apiKey.headers === "function" ? provider.apiKey.headers(connection.apiKey, settings) : {};
+  }
+  return {
+    // readable-check: allow method-probe - optional operation: oauthHeaders is an optional hook of the provider definition
+    ...(typeof provider.oauthHeaders === "function" ? provider.oauthHeaders({ clientId: connection.clientId }) : {}),
+    Authorization: `Bearer ${connection.tokens.accessToken}`
+  };
+}
+
+// A signal that aborts at the timeout or with the caller's signal.
+function requestSignal(signal, timeoutMs) {
+  const timeout = AbortSignal.timeout(timeoutMs);
+  return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+
+// 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, messageCode: "connectors.connection.checkOperationInputValues" });
+    failure.fieldErrors = error.fieldErrors;
+    if (error.fieldErrorCodes) failure.fieldErrorCodes = error.fieldErrorCodes;
+    throw failure;
+  }
+}
+
+/**
+ * The requests a connection sends its provider: operations, and the token
+ * grants that keep the connection's access current.
+ * @param {object} dependencies
+ * @param {typeof globalThis.fetch} dependencies.fetchImpl
+ * @param {() => number} dependencies.now
+ * @param {import("./types.js").ResolveReference} dependencies.resolveReference
+ */
+function createProviderRequests({ fetchImpl, now, resolveReference }) {
+  const http = createHttpClient({ fetchImpl, csrf: { enabled: false }, credentials: "omit" });
+
+  /**
+   * The oauth4webapi options of an OAuth token request: the fetch that sends
+   * it in the provider's token request encoding, and its timeout joined with
+   * the caller's signal.
+   * @param {AbortSignal | undefined} signal
+   * @param {ConnectionProvider} provider
+   */
+  function tokenRequestOptions(signal, provider) {
+    return {
+      [oauth.customFetch]: provider.tokenRequestEncoding === "json" ? (address, options) => {
+        const headers = new Headers(options.headers);
+        headers.set("Content-Type", "application/json");
+        return fetchImpl(address, { ...options, headers,
+          body: JSON.stringify(Object.fromEntries(new URLSearchParams(options.body))) });
+      } : fetchImpl,
+      signal: requestSignal(signal, REQUEST_TIMEOUT_MS)
+    };
+  }
+
+  /**
+   * @param {ConnectionProvider} provider
+   * @param {string} operationId
+   * @param {any} input
+   * @param {Record<string, any>} connection
+   * @param {AbortSignal} [signal]
+   */
+  async function request(provider, operationId, input, connection, signal) {
+    const operation = provider.operations[operationId];
+    if (!operation || !Object.hasOwn(provider.operations, operationId)) {
+      throw new ConnectorError("connector_operation_unknown", "This provider operation is not available.", { messageCode: "connectors.connection.providerOperationNotAvailable" });
+    }
+    if (["oauth2", "service-account"].includes(connection.method || "oauth2")) {
+      requireOperationScope(operation, connection.grantedScopes, "Connect again with the permission required for this operation.", { messageCode: "connectors.connection.connectAgainPermissionRequiredOperation" });
+    }
+    const settings = connection.settings || {};
+    const descriptor = operationRequest(operation, input, settings, connection.providerData);
+    const url = new URL(descriptor.url);
+    // readable-check: allow method-probe - data: a provider definition gives apiOrigins as a list or as a function of the settings
+    const origins = typeof provider.apiOrigins === "function" ? provider.apiOrigins(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.", { messageCode: "connectors.connection.providerOperationInvalidDestination" });
+    }
+    // readable-check: allow method-probe - optional operation: apiKey.pathPrefix is an optional hook of the provider definition
+    if (connection.method === "api-key" && typeof provider.apiKey.pathPrefix === "function") {
+      const prefix = provider.apiKey.pathPrefix(connection.apiKey);
+      if (typeof prefix !== "string" || !prefix.startsWith("/") || prefix.startsWith("//") ||
+        /[?#\\]/.test(prefix) || prefix.split("/").some((part) => /^(?:\.|%2e){1,2}$/i.test(part))) {
+        throw new ConnectorError("connector_request_invalid", "This provider has an invalid credential path.", { messageCode: "connectors.connection.providerInvalidCredentialPath" });
+      }
+      // A pathname assignment cannot replace the already checked origin.
+      url.pathname = prefix + url.pathname;
+    }
+    if (connection.method === "api-key" && provider.apiKey.queryParameter) {
+      url.searchParams.set(provider.apiKey.queryParameter, connection.apiKey);
+    }
+    let body = descriptor.body;
+    if (connection.method === "api-key" && provider.apiKey.bodyParameter) {
+      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.", { messageCode: "connectors.connection.providerRequiresJsonRequestBody" });
+      }
+      body = { ...body, [provider.apiKey.bodyParameter]: connection.apiKey };
+    }
+    const options = {
+      method: descriptor.method,
+      body,
+      headers: { ...descriptor.headers, Accept: "application/json", ...credentialHeaders(provider, connection, settings) },
+      redirect: "error",
+      signal: requestSignal(signal, provider.requestTimeoutMs)
+    };
+    let result;
+    try {
+      // readable-check: allow method-probe - optional operation: exchange is an optional hook of the provider definition
+      result = typeof provider.exchange === "function"
+        ? await provider.exchange(url.href, options, { fetchImpl, request: http.request, resolveReference,
+          settings, apiKey: connection.method === "api-key" ? connection.apiKey : undefined })
+        : await http.request(url.href, options);
+    } catch (error) {
+      // Transports can wrap cancellation in a network or protocol error.
+      options.signal.throwIfAborted();
+      throw error;
+    }
+    // The validator also receives the operation's own request, so it can check the provider answered what was asked.
+    // readable-check: allow method-probe - optional operation: validateResult is an optional hook of the provider definition
+    if (typeof operation.validateResult === "function" && !operation.validateResult(result, descriptor)) {
+      throw new ConnectorError("connector_response_invalid", "The provider returned an unexpected response.", { statusCode: 502, messageCode: "connectors.connection.providerReturnedUnexpectedResponse" });
+    }
+    return result;
+  }
+
+  /**
+   * @param {any} response
+   * @param {Record<string, any> | null} previous
+   * @param {string[]} requestedScopes
+   * @param {ConnectionProvider} provider
+   */
+  function tokensFrom(response, previous, requestedScopes, provider) {
+    return {
+      // readable-check: allow method-probe - optional operation: dataFromTokenResponse is an optional hook of the provider definition
+      ...(typeof provider.dataFromTokenResponse === "function" ? { providerData: provider.dataFromTokenResponse(response, previous?.providerData) } : {}),
+      tokens: {
+        accessToken: response.access_token,
+        refreshToken: response.refresh_token || previous?.tokens.refreshToken || null,
+        expiresAt: response.expires_in === undefined ? null : now() + response.expires_in * 1000
+      },
+      grantedScopes: response.scope === undefined
+        ? [...(previous?.grantedScopes || requestedScopes)]
+        : response.scope.split(provider.scopeSeparator).map((scope) => scope.trim()).filter(Boolean)
+    };
+  }
+
+  /**
+   * @param {Record<string, any>} integration
+   * @param {ConnectionProvider} provider
+   * @param {{ credential: string, fingerprint: string }} binding
+   * @param {AbortSignal} [signal]
+   */
+  async function serviceAccountGrant(integration, provider, binding, signal) {
+    const grantSignal = requestSignal(signal, provider.requestTimeoutMs);
+    grantSignal.throwIfAborted();
+    let response;
+    try {
+      response = await provider.serviceAccountGrant({
+        credential: binding.credential, settings: structuredClone(integration.settings),
+        scopes: [...integration.scopes], fetchImpl, signal: grantSignal, now: now()
+      });
+    } catch (error) {
+      grantSignal.throwIfAborted();
+      throw error;
+    }
+    grantSignal.throwIfAborted();
+    if (typeof response?.access_token !== "string" || !response.access_token || /\s/u.test(response.access_token) ||
+        // readable-check: allow optional-call - data: the provider's token response
+        response.token_type?.toLowerCase?.() !== "bearer" ||
+        !Number.isFinite(response.expires_in) || response.expires_in <= 0 || response.expires_in > 86_400 ||
+        response.refresh_token !== undefined || (response.scope !== undefined && typeof response.scope !== "string")) {
+      throw new ConnectorError("connector_response_invalid", "The provider returned an invalid service-account token.", { statusCode: 502, messageCode: "connectors.connection.providerReturnedInvalidServiceAccount" });
+    }
+    const grant = tokensFrom(response, null, integration.scopes, provider);
+    grant.grantedScopes = grant.grantedScopes.filter((scope) => integration.scopes.includes(scope));
+    return { ...grant, credentialFingerprint: binding.fingerprint };
+  }
+
+  /**
+   * @param {ConnectionProvider} provider
+   * @param {Record<string, any>} connection
+   * @param {any} verificationInput
+   * @param {string[]} requestedScopes
+   * @param {AbortSignal} [signal]
+   */
+  async function verifyOAuthConnection(provider, connection, verificationInput, requestedScopes, signal) {
+    const verification = await request(provider, provider.checkOperation, verificationInput, connection, signal);
+    // readable-check: allow method-probe - optional operation: accountLabelFromVerification is an optional hook of the provider definition
+    if (typeof provider.accountLabelFromVerification === "function") {
+      const label = provider.accountLabelFromVerification(verification);
+      if (typeof label !== "string" || !label.trim() || label.length > 256 || /[\p{Cc}\p{Cf}]/u.test(label)) {
+        throw new ConnectorError("connector_response_invalid", "The provider returned an invalid account label.", { statusCode: 502, messageCode: "connectors.connection.providerReturnedInvalidAccountLabel" });
+      }
+      connection.accountLabel = label;
+    }
+    // readable-check: allow method-probe - optional operation: grantedScopesFromVerification is an optional hook of the provider definition
+    if (typeof provider.grantedScopesFromVerification !== "function") return;
+    const scopes = provider.grantedScopesFromVerification(verification, { clientId: connection.clientId });
+    if (!Array.isArray(scopes) || scopes.some((scope) => typeof scope !== "string" || !scope)) {
+      throw new ConnectorError("connector_response_invalid", "The provider returned an invalid permission grant.", { statusCode: 502, messageCode: "connectors.connection.providerReturnedInvalidPermissionGrant" });
+    }
+    connection.grantedScopes = connection.grantedScopes.filter((scope) => requestedScopes.includes(scope) && scopes.includes(scope));
+    requireOperationScope(provider.operations[provider.checkOperation], connection.grantedScopes, "Connect again with the permission required for verification.", { messageCode: "connectors.connection.connectAgainPermissionRequiredVerification" });
+  }
+
+  /**
+   * @param {Record<string, any>} registration
+   * @param {ConnectionProvider} provider
+   * @param {Record<string, any>} settings
+   * @param {string[]} scopes
+   * @param {AbortSignal} [signal]
+   */
+  async function clientCredentialsGrant(registration, provider, settings, scopes, signal) {
+    const response = await oauth.clientCredentialsGrantRequest(
+      registration.oauth, registration.client, registration.clientAuth,
+      { scope: scopes.join(provider.scopeSeparator), ...(registration.resource ? { resource: registration.resource } : {}) },
+      tokenRequestOptions(signal, provider)
+    );
+    const result = await oauth.processClientCredentialsResponse(registration.oauth, registration.client,
+      await tokenResponse(provider, response, { settings, grantType: "client_credentials" }));
+    const grant = tokensFrom(result, null, scopes, provider);
+    // Client credentials renew with the application's secret, never a user refresh token.
+    grant.tokens.refreshToken = null;
+    grant.grantedScopes = grant.grantedScopes.filter((scope) => scopes.includes(scope));
+    return grant;
+  }
+
+  return Object.freeze({
+    tokenRequestOptions,
+    request,
+    tokensFrom,
+    serviceAccountGrant,
+    verifyOAuthConnection,
+    clientCredentialsGrant
+  });
+}
+
+export { connectionProvider, createProviderRequests, operationRequest, requireOperationScope, tokenResponse };

package/src/server/types.js

@@ -0,0 +1,150 @@
+// The type of the `connectors.core` capability, for features that require it,
+// and the contracts of what an application passes createConnectionService().
+
+/** @typedef {ReturnType<typeof import("./connectionService.js").createConnectionService>} ConnectorsCore */
+/** @typedef {Parameters<typeof import("./connectionService.js").createConnectionService>[0]} ConnectionServiceOptions */
+/** @typedef {ReturnType<typeof import("./credentialProtection.js").createCredentialProtection>} CredentialProtection */
+
+/**
+ * The application identity a connection belongs to: one application and one
+ * user or shared subject in it.
+ * @typedef {object} ConnectionOwner
+ * @property {string} applicationId
+ * @property {string} subjectId
+ */
+
+/**
+ * What a connector asks the application's access policy to decide.
+ * @typedef {object} ConnectorAuthorizationRequest
+ * @property {string} integrationId
+ * @property {string} operation The provider operation, or a connection step such as "connect", "status" or "disconnect".
+ * @property {string} accountMode The integration's account mode: "shared", "per-user" or "assistant".
+ * @property {{ action: string, decision: string }} [assistantPermission]
+ *   In assistant execution, the assistant action and its configured decision ("ask" or "always").
+ * @property {unknown} [input] A copy of the operation's input, for an operation that has one.
+ */
+
+/**
+ * The application's access policy: the owner whose connection the request may
+ * use, or null to deny it. An assistant action whose decision is "ask" also
+ * needs `approved: true`.
+ * @typedef {(context: any, request: ConnectorAuthorizationRequest) => Promise<(ConnectionOwner & { approved?: boolean }) | null>} ConnectorAuthorize
+ */
+
+/**
+ * Resolves a binding reference such as `env:NAME` to its value. Resolvers of
+ * per-user accounts also receive the authorized owner and the integration slot.
+ * @typedef {(reference: string, owner?: ConnectionOwner, slot?: { integrationId: string, accountMode: string, providerId: string }) => Promise<string>} ResolveReference
+ */
+
+/**
+ * A caller's request about one integration: the application context that
+ * authorize() receives and the integration's id.
+ * @typedef {object} IntegrationRequest
+ * @property {any} context
+ * @property {string} integrationId
+ */
+
+/**
+ * A request that may reach the provider, which `signal` cancels.
+ * @typedef {IntegrationRequest & { signal?: AbortSignal }} ProviderRequest
+ */
+
+/**
+ * A request that connects an account, with the input its verification takes.
+ * @typedef {ProviderRequest & { verificationInput?: Record<string, any> }} ConnectRequest
+ */
+
+/**
+ * One connection's stored state, held under the store's lock while work runs.
+ * @typedef {object} ConnectionRecord
+ * @property {Record<string, any> | null} connection The stored connection, or null.
+ * @property {(connection: object) => Promise<void>} save
+ * @property {() => Promise<void>} remove Removes the connection and its authorization attempts.
+ * @property {(attempt: Record<string, any> & { state: string, expiresAt: number }) => Promise<void>} putAttempt Stores an authorization attempt under its state.
+ * @property {(query: { after: number }) => Promise<Record<string, any> | null>} latestAttempt The newest attempt that expires after `after`.
+ * @property {(state: string) => Promise<Record<string, any> | null>} consumeAttempt Removes and answers the attempt with this state.
+ */
+
+/**
+ * Where connections are kept: createKnexConnectionStore(),
+ * createFileConnectionStore() or the application's own store.
+ * @typedef {object} ConnectionStore
+ * @property {<T>(slot: { owner: ConnectionOwner, integrationId: string }, work: (record: ConnectionRecord) => Promise<T>) => Promise<T>} withConnection
+ */
+
+/**
+ * The request a provider operation sends.
+ * @typedef {object} ConnectorRequest
+ * @property {string} method
+ * @property {string} url
+ * @property {Record<string, string>} [headers]
+ * @property {any} [body]
+ */
+
+/**
+ * One operation a provider offers.
+ * @typedef {object} ConnectorOperation
+ * @property {string[]} scopes The permissions of which one must be granted; an empty list always runs.
+ * @property {(input: any, settings: Record<string, any>, providerData?: any) => ConnectorRequest} request
+ *   Builds the request for an input; throws an error with `fieldErrors` for an invalid one.
+ * @property {(result: any, request: ConnectorRequest) => boolean} [validateResult] Answers whether the response is what was asked.
+ * @property {string} [assistantAction] The assistant action whose permission covers it; its operation id otherwise.
+ * @property {string[]} [authenticationMethods] The credential modes it runs with; every mode otherwise.
+ */
+
+/**
+ * What a provider's exchange() receives besides the URL and the request options.
+ * @typedef {object} ConnectorExchangeTransport
+ * @property {typeof globalThis.fetch} fetchImpl
+ * @property {ReturnType<typeof import("@jskit-ai/http-runtime/client").createHttpClient>["request"]} request The parsed-JSON HTTP client.
+ * @property {ResolveReference} resolveReference
+ * @property {Record<string, any>} settings
+ * @property {string | undefined} apiKey The API key of an API-key connection; undefined otherwise.
+ */
+
+/**
+ * A connector provider: its shared definition (id, scopes, credential modes,
+ * account modes and settings, which validateIntegrationConfiguration() reads)
+ * and the server runtime createConnectionService() calls. A field given as a
+ * value or as a function of the settings may take either form.
+ * @typedef {object} ConnectorProvider
+ * @property {string} id
+ * @property {Record<string, ConnectorOperation>} operations
+ * @property {string | ((method: string) => string)} checkOperation The operation that verifies a connection.
+ * @property {string[] | ((settings: Record<string, any>, providerData?: any) => string[])} apiOrigins The HTTPS origins its requests may reach.
+ * @property {(settings: Record<string, any>) => string[]} [authenticationMethodsForSettings] The credential modes for these settings, in place of the definition's list.
+ * @property {(settings: Record<string, any>) => string[]} [accountModesForSettings] The account modes for these settings, in place of the definition's list.
+ * @property {(grantType: string, settings: Record<string, any>) => Array<{ value: string }>} [scopesForGrantType] The scopes an OAuth grant type offers.
+ * @property {(settings: Record<string, any>) => Array<{ value: string }>} [scopesForSettings] The scopes for these settings, in place of the definition's list.
+ * @property {(clientId: string) => unknown} [validateClientId] True for a client ID the provider accepts; otherwise its field error.
+ * @property {(settings: Record<string, any>) => object} [runtimeForSettings] Runtime fields that replace these for the integration's settings.
+ * @property {Array<{ value: string }>} [assistantActions]
+ * @property {number} [requestTimeoutMs] The timeout of its operations and service-account grants. Defaults to 15 seconds, the timeout of every OAuth token request.
+ * @property {string} [scopeSeparator] Defaults to a space.
+ * @property {object | ((settings: Record<string, any>) => object)} [oauth] The OAuth authorization server metadata.
+ * @property {string | ((settings: Record<string, any>) => string)} [oauthResource]
+ * @property {boolean} [oauthPkce] False for a provider without PKCE.
+ * @property {string} [oauthBasicEncoding] "raw" sends Basic client credentials without form encoding.
+ * @property {string} [oauthClientIdParameter] The parameter that carries the client ID, when it is not `client_id`.
+ * @property {(client: { clientId: string }) => Record<string, string>} [oauthHeaders]
+ * @property {Record<string, string>} [authorizationParameters]
+ * @property {(settings: Record<string, any>) => string | undefined} [authorizationScopeParameter]
+ * @property {boolean} [scopesInAuthorizationResponse]
+ * @property {string} [tokenRequestEncoding] "json" sends every token request as JSON instead of a form.
+ * @property {number} [tokenRefreshLeewayMs] Defaults to 30 seconds.
+ * @property {boolean} [refreshRequiresRedirectUri]
+ * @property {(callbackUrl: string) => boolean} [validateCallbackUrl]
+ * @property {(response: Response, details: { settings: Record<string, any>, grantType: string }) => Response | Promise<Response>} [normalizeTokenResponse]
+ * @property {(response: any, previous: any) => any} [dataFromTokenResponse]
+ * @property {(verification: any) => string} [accountLabelFromVerification]
+ * @property {(verification: any, client: { clientId: string }) => string[]} [grantedScopesFromVerification]
+ * @property {(request: { credential: string, settings: Record<string, any>, scopes: string[], fetchImpl: typeof globalThis.fetch, signal: AbortSignal, now: number }) => Promise<any>} [serviceAccountGrant]
+ * @property {{ headers?: (apiKey: string, settings: Record<string, any>) => Record<string, string>, queryParameter?: string, bodyParameter?: string, pathPrefix?: (apiKey: string) => string }} [apiKey]
+ *   Where an API-key connection places its key.
+ * @property {boolean} [apiKeySecretOptional]
+ * @property {(url: string, options: object, transport: ConnectorExchangeTransport) => Promise<any>} [exchange]
+ *   Sends the request itself, for a protocol such as MCP or AWS Signature Version 4.
+ */
+
+export {};