@jskit-ai/connectors-core 0.2.3 → 0.2.5

package/src/shared/configuration.js

@@ -92,17 +92,23 @@ const FIELD_ERRORS = Object.freeze({
   clientId: { code: "connectors.configuration.clientId", message: "Check this provider's client identifier." },
   requiredScopes: { code: "connectors.configuration.requiredScopes", message: "Include this provider's required permissions." },
   scopeUnsupported: { code: "connectors.configuration.scopeUnsupported", message: "A selected permission is not supported by this provider configuration." },
-  scopeRequired: { code: "connectors.configuration.scopeRequired", message: "Select at least one permission." }
+  scopeRequired: { code: "connectors.configuration.scopeRequired", message: "Select at least one permission." },
+  secretReference: { code: "connectors.configuration.secretReference", message: "Use a reference such as env:VARIABLE_NAME." }
 });
 
-// A schema validation error's field errors with the codes the validator gave them.
+// A schema validation error's field errors with the codes the validator gave them. A
+// credential reference that fails secretReference's pattern says what a reference looks like.
 function schemaFieldErrors(error, fallback, prefix = "") {
   const messages = {};
   const codes = {};
   for (const [field, message] of Object.entries(error.fieldErrors || fallback)) {
-    messages[`${prefix}${field}`] = message;
     const coded = error.fieldErrorCodes?.[field];
-    if (coded) codes[`${prefix}${field}`] = coded;
+    if (coded?.code === "kernel.validation.field.pattern" && coded.params.pattern === secretReference.pattern) {
+      messages[`${prefix}${field}`] = FIELD_ERRORS.secretReference;
+    } else {
+      messages[`${prefix}${field}`] = message;
+      if (coded) codes[`${prefix}${field}`] = coded;
+    }
   }
   return { messages, codes };
 }
@@ -116,8 +122,8 @@ const MESSAGE_KEY_SOURCE = Symbol.for("@jskit-ai/connectors-core.messageKeySourc
 
 // Provider definitions carry message keys, which connectors-web translates. Code that
 // shows a definition's texts itself gets the same definitions with every key (and every
-// { key, params } a function returns) rendered to the catalog's English, exactly as
-// before keys. Each English object keeps its keyed original under MESSAGE_KEY_SOURCE.
+// { key, params } a function returns) rendered to the catalog's English text. Each
+// English object keeps its keyed original under MESSAGE_KEY_SOURCE.
 function createEnglishProviderTexts(catalog) {
   const rendered = new WeakMap();
   const englishMessage = (key, params) => {
@@ -168,25 +174,31 @@ function providerGrantTypes(provider) {
 }
 
 function getProviderSettingsSchema(provider, settings = {}) {
+  // readable-check: allow method-probe - data: a provider definition gives its settings schema as a schema or as a function of the settings
   return typeof provider.settingsSchema === "function" ? provider.settingsSchema(settings) : provider.settingsSchema;
 }
 
 function getProviderAuthenticationMethods(provider, settings = {}) {
-  return provider.authenticationMethodsForSettings ? provider.authenticationMethodsForSettings(settings) : provider.authenticationMethods;
+  // readable-check: allow method-probe - optional operation: authenticationMethodsForSettings is an optional hook of the provider definition
+  return typeof provider.authenticationMethodsForSettings === "function" ? provider.authenticationMethodsForSettings(settings) : provider.authenticationMethods;
 }
 
 function getProviderAccountModes(provider, settings = {}) {
-  return provider.accountModesForSettings ? provider.accountModesForSettings(settings) : provider.accountModes;
+  // readable-check: allow method-probe - optional operation: accountModesForSettings is an optional hook of the provider definition
+  return typeof provider.accountModesForSettings === "function" ? provider.accountModesForSettings(settings) : provider.accountModes;
 }
 
 function getProviderScopes(provider, settings = {}, grantType = DEFAULT_GRANT_TYPE, authenticationMethod) {
-  const scopes = provider.scopesForGrantType ? provider.scopesForGrantType(grantType, settings)
-    : provider.scopesForSettings ? provider.scopesForSettings(settings) : provider.scopes;
+  // readable-check: allow method-probe - optional operation: scopesForGrantType is an optional hook of the provider definition
+  const scopes = typeof provider.scopesForGrantType === "function" ? provider.scopesForGrantType(grantType, settings)
+    // readable-check: allow method-probe - optional operation: scopesForSettings is an optional hook of the provider definition
+    : typeof provider.scopesForSettings === "function" ? provider.scopesForSettings(settings) : provider.scopes;
   return authenticationMethod ? scopes.filter(scope => !scope.authenticationMethods || scope.authenticationMethods.includes(authenticationMethod)) : scopes;
 }
 
 function getProviderClientAuthenticationMethods(provider, grantType = DEFAULT_GRANT_TYPE, settings = {}) {
   const methods = provider.oauthClientAuthenticationMethods;
+  // readable-check: allow method-probe - data: a provider definition gives its client authentication methods as a list or as a function of the grant type
   return typeof methods === "function" ? methods(grantType, settings) : methods || [DEFAULT_TOKEN_ENDPOINT_AUTH_METHOD];
 }
 
@@ -194,12 +206,15 @@ function getProviderClientAuthenticationMethods(provider, grantType = DEFAULT_GR
 function getProviderSetup(provider, settings = {}, authenticationMethod) {
   const setup = provider.setup || {};
   return {
+    // readable-check: allow optional-call - data: a provider definition's setup may give its URL for the settings
     url: setup.urlForSettings?.(settings, authenticationMethod) || setup.urlByAuthentication?.[authenticationMethod] || setup.url,
+    // readable-check: allow optional-call - data: a provider definition's setup may give its steps for the settings
     steps: setup.stepsForSettings?.(settings, authenticationMethod) || setup.stepsByAuthentication?.[authenticationMethod] || setup.steps
   };
 }
 
 function isProviderConfigurationOnly(provider, settings = {}) {
+  // readable-check: allow optional-call - data: a provider definition may say per settings whether it is configuration only
   return Boolean(provider.configurationOnly || provider.configurationOnlyForSettings?.(settings));
 }
 
@@ -296,15 +311,16 @@ function validateIntegrationConfiguration(input, { providers = [], allowUnknownP
           Object.assign(fieldErrorCodes, codes);
         }
       }
+      const settings = integration.settings || {};
       for (const field of provider.settingsFields || []) {
-        if (field.authenticationMethods && !field.authenticationMethods.includes(auth.method) && Object.hasOwn(integration.settings || {}, field.name)) {
+        if (field.authenticationMethods && !field.authenticationMethods.includes(auth.method) && Object.hasOwn(settings, field.name)) {
           fieldErrors[`${path}.settings.${field.name}`] = FIELD_ERRORS.otherCredentialModeSetting;
         }
       }
-      if (!getProviderAccountModes(provider, integration.settings || {}).includes(integration.accountMode)) {
+      if (!getProviderAccountModes(provider, settings).includes(integration.accountMode)) {
         fieldErrors[`${path}.accountMode`] = FIELD_ERRORS.accountModeUnsupported;
       }
-      if (!getProviderAuthenticationMethods(provider, integration.settings).includes(auth.method)) {
+      if (!getProviderAuthenticationMethods(provider, settings).includes(auth.method)) {
         fieldErrors[`${path}.authentication.method`] = FIELD_ERRORS.credentialModeUnsupported;
       }
       if (auth.method === "oauth2" && registration?.source === "own") {
@@ -312,16 +328,17 @@ function validateIntegrationConfiguration(input, { providers = [], allowUnknownP
         if (!providerGrantTypes(provider).includes(grantType)) {
           fieldErrors[`${registrationPath}.grantType`] = FIELD_ERRORS.oauthFlowUnsupported;
         }
-        const methods = getProviderClientAuthenticationMethods(provider, grantType, integration.settings || {});
+        const methods = getProviderClientAuthenticationMethods(provider, grantType, settings);
         if (!methods.includes(registrationClientAuthentication(registration))) {
           fieldErrors[`${registrationPath}.tokenEndpointAuthMethod`] = FIELD_ERRORS.clientAuthenticationUnsupported;
         }
-        if (registration.clientId && provider.validateClientId) {
+        // readable-check: allow method-probe - optional operation: validateClientId is an optional hook of the provider definition
+        if (registration.clientId && typeof provider.validateClientId === "function") {
           const result = provider.validateClientId(registration.clientId);
           if (result !== true) fieldErrors[`${registrationPath}.clientId`] = result || FIELD_ERRORS.clientId;
         }
       }
-      const scopes = getProviderScopes(provider, integration.settings || {}, grantType, auth.method);
+      const scopes = getProviderScopes(provider, settings, grantType, auth.method);
       const allowedScopes = new Set(scopes.map((scope) => scope.value));
       if (scopes.some((scope) => scope.required && !integration.scopes.includes(scope.value))) {
         fieldErrors[`${path}.scopes`] = FIELD_ERRORS.requiredScopes;

package/test/connectionService.test.js

@@ -5,11 +5,15 @@ import assert from "node:assert/strict";
 import test from "node:test";
 import Fastify from "fastify";
 import { createCapabilityRuntime, defineProvider } from "@jskit-ai/kernel/shared/capabilities";
-import { createActionProvider } from "@jskit-ai/kernel/server/actions";
+import { ActionProvider } from "@jskit-ai/kernel/server/actions";
+import { EventProvider } from "@jskit-ai/kernel/server/runtime";
+import { silentLogger } from "@jskit-ai/kernel/server/runtime/logger";
 import { googleCalendarProvider } from "../../connector-google-calendar/src/server/provider.js";
 import { createConnectionService, createConnectorsFeature, createEnvironmentReferenceResolver } from "../src/server/index.js";
 import { integrationsSchema, parseIntegrationConfiguration, validateIntegrationConfiguration } from "../src/shared/configuration.js";
 import { clickhouseProvider } from "../../connectors-catalog/src/server/clickhouse.js";
+import { algoliaDefinition } from "../../connectors-catalog/src/shared/algolia.js";
+import { firebaseCloudMessagingDefinition, firebaseMessagingScope } from "../../connectors-catalog/src/shared/firebase-cloud-messaging.js";
 
 const listScope = "https://www.googleapis.com/auth/calendar.calendarlist.readonly";
 const eventsScope = "https://www.googleapis.com/auth/calendar.events.readonly";
@@ -111,8 +115,8 @@ test("the ordinary credential-free Feature action verifies without resolving ref
       return Response.json({ meta: [], data: [{ ok: 1, user: "default" }], rows: 1 });
     }
   };
-  const runtime = createCapabilityRuntime({ providers: [
-    createActionProvider(), createConnectorsFeature(options),
+  const runtime = createCapabilityRuntime({ inputs: { "runtime.logger": silentLogger }, providers: [
+    EventProvider, ActionProvider, createConnectorsFeature(options),
     defineProvider({ id: "test.credential-free-observer", requires: { catalogue: "runtime.actions" }, setup({ catalogue }) { actions = catalogue; } })
   ] });
   await runtime.start();
@@ -395,7 +399,7 @@ test("cancelling a service token exchange preserves the previous grant without r
 test("the client credentials Feature action uses the ordinary application policy and runtime", async () => {
   const { options } = serviceAccountSetup();
   let actions;
-  const runtime = createCapabilityRuntime({ providers: [createActionProvider(), createConnectorsFeature(options),
+  const runtime = createCapabilityRuntime({ inputs: { "runtime.logger": silentLogger }, providers: [EventProvider, ActionProvider, createConnectorsFeature(options),
     defineProvider({ id: "test.service-observer", requires: { catalogue: "runtime.actions" }, setup({ catalogue }) { actions = catalogue; } })] });
   await runtime.start();
   try {
@@ -487,6 +491,44 @@ test("reference fields reject pasted web URLs while preserving environment and c
   }
 });
 
+function assertReferenceFieldError(input, providers, field) {
+  assert.throws(() => validateIntegrationConfiguration(input, { providers }), (error) => {
+    assert.equal(error.fieldErrors[field], "Use a reference such as env:VARIABLE_NAME.", field);
+    assert.deepEqual(error.fieldErrorCodes[field], { code: "connectors.configuration.secretReference", params: {} }, field);
+    return true;
+  });
+}
+
+test("a secretRef that is not a reference says to use a reference such as env:VARIABLE_NAME", () => {
+  for (const value of ["https://x", "plain"]) {
+    assertReferenceFieldError(databaseConfiguration({ method: "api-key", secretRef: value }), [clickhouseProvider], "integrations.database.authentication.secretRef");
+  }
+});
+
+test("a registration clientSecretRef that is not a reference says to use a reference such as env:VARIABLE_NAME", () => {
+  for (const value of ["https://x", "plain"]) {
+    const input = configuration();
+    input.registrations.google.clientSecretRef = value;
+    assertReferenceFieldError(input, [googleCalendarProvider], "registrations.google.clientSecretRef");
+  }
+});
+
+test("a provider setting's reference says the same, while its other pattern failures keep the kernel's sentence", () => {
+  const input = { schemaVersion: 1, registrations: {}, integrations: {
+    search: { provider: "algolia", accountMode: "shared", scopes: [], authentication: { method: "api-key", secretRef: "env:ALGOLIA_KEY" },
+      settings: { applicationId: "APP1", publicApiKeyRef: "raw-search-key" } },
+    push: { provider: "firebase-cloud-messaging", accountMode: "shared", scopes: [firebaseMessagingScope], authentication: { method: "service-account", secretRef: "env:FCM" },
+      settings: { projectId: "push-project", clientMode: "web", apiKey: "not-a-key" } }
+  } };
+  const providers = [algoliaDefinition, firebaseCloudMessagingDefinition];
+  assertReferenceFieldError(input, providers, "integrations.search.settings.publicApiKeyRef");
+  assert.throws(() => validateIntegrationConfiguration(input, { providers }), (error) => {
+    assert.equal(error.fieldErrors["integrations.push.settings.apiKey"], "Value does not match the required pattern.");
+    assert.equal(error.fieldErrorCodes["integrations.push.settings.apiKey"].code, "kernel.validation.field.pattern");
+    return true;
+  });
+});
+
 test("the exported configuration contract enforces reference constraints for every credential field", async (t) => {
   const app = Fastify({ ajv: { plugins: [(ajv) => ajv.addKeyword("x-json-rest-schema")] } });
   t.after(() => app.close());
@@ -828,8 +870,8 @@ test("configuration rejects gateway registrations before constructing a runtime"
 test("the Feature exposes ordinary JSKIT actions with application authorization", async () => {
   const { options } = setup();
   let actions;
-  const runtime = createCapabilityRuntime({ providers: [
-    createActionProvider(), createConnectorsFeature(options),
+  const runtime = createCapabilityRuntime({ inputs: { "runtime.logger": silentLogger }, providers: [
+    EventProvider, ActionProvider, createConnectorsFeature(options),
     defineProvider({
       id: "test.observer", requires: { catalogue: "runtime.actions" },
       setup({ catalogue }) { actions = catalogue; }
@@ -997,8 +1039,8 @@ test("JSON-body credentials replace supplied values, preserve input and reach th
     }
   };
   let actions;
-  const runtime = createCapabilityRuntime({ providers: [
-    createActionProvider(), createConnectorsFeature(options),
+  const runtime = createCapabilityRuntime({ inputs: { "runtime.logger": silentLogger }, providers: [
+    EventProvider, ActionProvider, createConnectorsFeature(options),
     defineProvider({ id: "test.body-observer", requires: { catalogue: "runtime.actions" }, setup({ catalogue }) { actions = catalogue; } })
   ] });
   await runtime.start();

package/test/serviceAccount.test.js

@@ -5,7 +5,9 @@ import { tmpdir } from "node:os";
 import path from "node:path";
 import { createSchema } from "json-rest-schema";
 import { createCapabilityRuntime, defineProvider } from "@jskit-ai/kernel/shared/capabilities";
-import { createActionProvider } from "@jskit-ai/kernel/server/actions";
+import { ActionProvider } from "@jskit-ai/kernel/server/actions";
+import { EventProvider } from "@jskit-ai/kernel/server/runtime";
+import { silentLogger } from "@jskit-ai/kernel/server/runtime/logger";
 import { createConnectionService, createConnectorsFeature } from "../src/server/index.js";
 import { ConnectorError } from "../src/server/errors.js";
 import { createFileConnectionStore, createCredentialProtection } from "../src/server/fileStorage.js";
@@ -182,7 +184,7 @@ test("service grants honor cancellation and deadlines without replay or partial
 
 test("the service-account Feature action uses the same application policy and verified runtime", async (t) => {
   const f = await fixture(t); let actions;
-  const runtime = createCapabilityRuntime({ providers: [createActionProvider(), createConnectorsFeature(f.options),
+  const runtime = createCapabilityRuntime({ inputs: { "runtime.logger": silentLogger }, providers: [EventProvider, ActionProvider, createConnectorsFeature(f.options),
     defineProvider({ id: "test.service-observer", requires: { catalogue: "runtime.actions" }, setup({ catalogue }) { actions = catalogue; } })] });
   await runtime.start();
   try {

package/test/setupCommand.test.js

@@ -16,9 +16,10 @@ const guide = await readFile(new URL("../docs/setup-command.md", import.meta.url
 const source = guide.match(/```js\n([\s\S]*?)\n```/u)?.[1];
 assert.ok(source, "The setup guide must contain its dispatch example.");
 const dispatchSetup = new Function(`${source}\nreturn dispatchSetup;`)();
+const protocol = "example-host.integration-setup.command.v1";
 const scope = "https://www.googleapis.com/auth/calendar.calendarlist.readonly";
 const callback = "http://127.0.0.1:8080/integrations/google/callback";
-const context = { applicationId: "dogandgroom-dev", subjectId: "business-account" };
+const context = { applicationId: "bookings-dev", subjectId: "business-account" };
 
 async function fixture(t) {
   const directory = await mkdtemp(path.join(tmpdir(), "setup-composition-"));
@@ -72,9 +73,9 @@ async function fixture(t) {
     }
   });
   const dispatch = async (operation, integrationId, extra = {}, identity = context) => {
-    const result = await dispatchSetup({ protocol: "vibe64.integration-setup.command.v1",
+    const result = await dispatchSetup({ protocol,
       requestId: "fixture-request", operation, integrationId, ...extra },
-    { configuration, connections: restart(), context: identity });
+    { protocol, configuration, connections: restart(), context: identity });
     assert.equal(result.requestId, "fixture-request");
     assert.equal(JSON.stringify(result).includes("private-"), false);
     return result;
@@ -123,14 +124,14 @@ try {
       return Response.json({ object: "list", data: [], has_more: false });
     }
   });
-  const result = await dispatchSetup(JSON.parse(input), { configuration, connections, context });
+  const result = await dispatchSetup(JSON.parse(input), { protocol: ${JSON.stringify(protocol)}, configuration, connections, context });
   process.stdout.write(JSON.stringify(result) + "\\n");
 } catch {
   process.stderr.write("Integration setup failed.\\n");
   process.exitCode = 1;
 }
 `);
-  const request = { protocol: "vibe64.integration-setup.command.v1", requestId: "cli-request", integrationId: "mail" };
+  const request = { protocol, requestId: "cli-request", integrationId: "mail" };
   for (const [operation, key, applicationId, expected, allowCheck] of [
     ["status", "MISSING", "first-app", "unconfigured", false],
     ["connect", "MISSING", "first-app", "unconfigured", false],
@@ -220,7 +221,7 @@ test("moving application state preserves grants and refresh while invalidating c
   const moved = `${directory}-relocated`;
   t.after(() => rm(moved, { recursive: true, force: true }));
   await rename(directory, moved);
-  env.CALLBACK = "https://dogandgroom.example/integrations/google/callback";
+  env.CALLBACK = "https://bookings.example/integrations/google/callback";
   const relocated = restart(moved);
   const requestCount = requests.length;
   assert.equal(await relocated.resumeAuthorization(input), null);
@@ -235,7 +236,7 @@ test("moving application state preserves grants and refresh while invalidating c
     "oauth2.googleapis.com", "www.googleapis.com"
   ]);
   assert.equal((await restart(moved).status(input)).status, "connected");
-  const otherEnvironment = { ...context, applicationId: "dogandgroom-production" };
+  const otherEnvironment = { ...context, applicationId: "bookings-production" };
   assert.equal((await relocated.status({ ...input, context: otherEnvironment })).status, "disconnected");
   await relocated.disconnect({ ...input, context: otherEnvironment });
   assert.equal((await relocated.status(input)).status, "connected");
@@ -259,7 +260,7 @@ test("documented OAuth setup resumes across restarts, preserves a grant on cance
   const callbackUrl = `${callback}?code=fixture-code&state=${pending.attemptId}`;
   await restart().completeAuthorization({ context, integrationId: "calendar", callbackUrl });
   assert.equal((await dispatch("status", "calendar")).status, "connected");
-  env.CALLBACK = "https://dogandgroom.example/integrations/google/callback";
+  env.CALLBACK = "https://bookings.example/integrations/google/callback";
   assert.equal((await dispatch("status", "calendar")).callbackUrl, env.CALLBACK);
   env.CALLBACK = callback;
   const replacement = await dispatch("connect", "calendar");