@jskit-ai/connectors-core 0.2.3 → 0.2.5

package/README.md

@@ -15,7 +15,7 @@ configuration validation.
 
 See [application-owned OAuth callbacks](docs/oauth-callbacks.md) for callback
 routes, environment bindings and changes of domain or hosting.
-The [application setup guide](docs/online-setup.md) explains credential and
+The [application setup guide](docs/application-setup.md) explains credential and
 runtime ownership for hosted editors and direct CLI use.
 
 ## Pre-release migration to application-owned connections
@@ -136,6 +136,11 @@ retain placeholders while an administrator finishes setup.
 Never trust owner IDs supplied by a browser. Include deployment/environment
 identity in `applicationId` when several environments share storage.
 
+`@jskit-ai/connectors-core/server/types` names these contracts for code that
+composes the service: `ConnectorAuthorize`, `ResolveReference`,
+`ConnectionStore`, `ConnectorProvider`, `ConnectionServiceOptions` and the
+`ConnectorsCore` service itself.
+
 For `invoke`, `input` is a separate copy of the caller's operation input. It is
 omitted for connection-management methods. Check it when permission depends on
 the requested tool, document or action. The service snapshots input before

package/docs/setup-command.md

@@ -4,35 +4,34 @@ An application can expose its connection setup to a CLI or an editor using the
 same `createConnectionService()` instance as its backend. JSKIT owns connection
 logic and optional stores; the application owns the executable, operator
 identity, environment, callback route and deployment. Neither the backend nor
-this library requires Vibe64 to run.
+this library requires a particular host to run.
 
-For Vibe64, the application declares its own command in its Stack:
-
-```markdown
-## Integration setup
-
-- Command with `nodejs` in `.`: `node` `scripts/integrations.js`
-```
+The host that runs the command (an editor, a CLI wrapper or an operations tool)
+says how the application declares it, for example as `node
+scripts/integrations.js`, and owns its request protocol: the protocol id that
+requests carry and responses echo, the input and output size bounds and the
+time limit.
 
 The script loads the application's existing configuration and server composition.
 Resolve administrator references from its existing Env using
-`createEnvironmentReferenceResolver()`. Use an application-owned store whose
+`createEnvironmentReferenceResolver(process.env)`. Use an application-owned store whose
 identity includes the environment. Keep runtime data outside source and release
 snapshots. The script's operator context must be established by the application;
 never accept applicationId, subjectId or administrator privileges from stdin.
 The normal service `authorize` callback still enforces connect/status/disconnect
-permissions. An editor user's identity is not an application user's identity.
+permissions. A host user's identity is not an application user's identity.
 
 ## Dispatch example
 
 The following function belongs in the application's script. It accepts the
-already-created service, validated configuration and trusted operator context.
-It is deliberately a composition example, not a new JSKIT command runner.
+already-created service, validated configuration, trusted operator context and
+the protocol id of the host that runs the command. It is deliberately a
+composition example, not a new JSKIT command runner.
 
 ```js
-async function dispatchSetup(request, { connections, configuration, context }) {
-  const { protocol, requestId, operation, integrationId } = request;
-  if (protocol !== "vibe64.integration-setup.command.v1" ||
+async function dispatchSetup(request, { protocol, connections, configuration, context }) {
+  const { requestId, operation, integrationId } = request;
+  if (request.protocol !== protocol ||
       typeof requestId !== "string" || !requestId ||
       !["status", "connect", "cancel", "disconnect"].includes(operation) ||
       !Object.hasOwn(configuration.integrations, integrationId)) {
@@ -94,11 +93,12 @@ async function dispatchSetup(request, { connections, configuration, context }) {
 }
 ```
 
-Read exactly one JSON request from stdin with a 32 KiB bound. Write only the
-returned JSON object plus a newline to stdout. On failure exit nonzero; do not
-print credentials, provider responses or raw exceptions. Close the application's
-database pool/resources in `finally`. The editor bounds the command at 30 seconds;
-return pending immediately instead of waiting for browser consent.
+Read exactly one JSON request from stdin within the host's input bound. Write
+only the returned JSON object plus a newline to stdout. On failure exit nonzero;
+do not print credentials, provider responses or raw exceptions. Close the
+application's database pool/resources in `finally`. The host bounds the
+command's time; return pending immediately instead of waiting for browser
+consent.
 
 `verificationInput` supplies provider-specific check inputs such as a resource
 ID. It is not a credential entry channel. Keys and client secrets belong in Env.
@@ -107,11 +107,11 @@ A configuration save does not verify credentials or produce a connected state.
 Status validates required local bindings without calling the provider. Before a
 first connection, missing credentials or an invalid callback produce
 `unconfigured` with a safe `configurationError` code; the dispatcher maps that
-code to the editor's setup guidance. A previous grant remains available for
+code to the host's setup guidance. A previous grant remains available for
 disconnect and reports `reconnect-required` when its bindings are incomplete.
 For a valid authorization-code registration, status and pending authorization
 report `callbackUrl` resolved from the application's Env. This is the URL to
-register with the provider, not the editor's suggestion. Invalid or incomplete
+register with the provider, not one the host suggests. Invalid or incomplete
 bindings do not expose an unvalidated callback or private Env values.
 
 Providers may expose `accountLabel` from their verified account response. Gmail
@@ -127,7 +127,7 @@ the grant; cancelled replacement consent retains the previous grant's label.
 
 ### Individual application accounts
 
-For `accountMode: "per-user"`, the editor configures the OAuth client but does
+For `accountMode: "per-user"`, the host configures the OAuth client but does
 not run this shared-operator dispatcher. The application implements its own
 connection screen using its existing UI and authenticated routes:
 
@@ -141,7 +141,7 @@ connection screen using its existing UI and authenticated routes:
 
 Supply `{ context, integrationId }` to each operation. Derive `context` from
 trusted application authentication and membership, never a form field, callback
-query or editor identity. The service's `authorize` function must enforce the
+query or host identity. The service's `authorize` function must enforce the
 application and user boundary. Keep registration credentials in backend Env;
 each user's grant lives separately in the existing connection store. The browser
 receives only safe status/consent metadata. OAuth callback state does not replace
@@ -162,7 +162,7 @@ The callback Env value must match both this real route and the provider's
 registered redirect URI. For a hosted project use its assigned application URL
 as the starting origin, then append the implemented callback path. Custom domains
 or explicit overrides require updating that Env value and provider registration;
-changing an editor hostname cannot change application identity.
+changing the host's hostname cannot change application identity.
 
 Status can recover a still-valid pending attempt after the process restarts.
 Cancellation consumes its state and preserves an earlier working connection.

package/locales/en.json

@@ -27,6 +27,7 @@
         "schemaVersionUnsupported": "Use numeric schemaVersion 1; other versions require an explicit migration.",
         "scopeRequired": "Select at least one permission.",
         "scopeUnsupported": "A selected permission is not supported by this provider configuration.",
+        "secretReference": "Use a reference such as env:VARIABLE_NAME.",
         "serviceAccountPerUser": "A service account cannot connect as each app user.",
         "serviceAccountRegistration": "Service-account credentials do not use a browser OAuth registration.",
         "stableName": "Use a stable lowercase name containing letters, digits and hyphens.",
@@ -55,7 +56,6 @@
         "providerClientIdNotConfigured": "The provider client ID is not configured.",
         "providerDeniedOperation": "The provider denied this operation.",
         "providerDoesNotDeclareAssistant": "This provider does not declare this assistant action.",
-        "providerDoesNotImplementService": "This provider does not implement service-account authorization.",
         "providerInvalidCredentialPath": "This provider has an invalid credential path.",
         "providerNonPkceFlowRequires": "This provider's non-PKCE flow requires a confidential client.",
         "providerOperationInvalidDestination": "The provider operation has an invalid destination.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/connectors-core",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Portable integration configuration and server-side account connection runtime.",
   "type": "module",
   "scripts": {
@@ -11,6 +11,7 @@
     "./server": "./src/server/index.js",
     "./server/storage": "./src/server/storage.js",
     "./server/file-storage": "./src/server/fileStorage.js",
+    "./server/types": "./src/server/types.js",
     "./locales/en.json": "./locales/en.json"
   },
   "dependencies": {
@@ -54,7 +55,7 @@
     }
   },
   "peerDependencies": {
-    "@jskit-ai/http-runtime": "0.2.3",
-    "@jskit-ai/kernel": "0.2.3"
+    "@jskit-ai/http-runtime": "0.2.4",
+    "@jskit-ai/kernel": "0.2.4"
   }
 }

package/src/server/ConnectorsFeature.js

@@ -2,6 +2,70 @@ import { defineFeature } from "@jskit-ai/kernel/server/features";
 import { createSchema } from "json-rest-schema";
 import { createConnectionService } from "./connectionService.js";
 
+const integrationId = Object.freeze({ type: "string", required: true, minLength: 1, maxLength: 200 });
+const verificationInput = Object.freeze({ type: "object", additionalProperties: true });
+// Every connectors action serves API and internal callers on app surfaces.
+const connectorsActionReach = Object.freeze({
+  channels: Object.freeze(["api", "internal"]),
+  surfaces: Object.freeze(["app"])
+});
+
+/** @param {{ connections: import("./types.js").ConnectorsCore }} dependencies */
+function createConnectorsActions({ connections }) {
+  return Object.freeze([
+    Object.freeze({
+      id: "connectors.status",
+      kind: "query",
+      ...connectorsActionReach,
+      input: { schema: createSchema({ integrationId }) },
+      execute: (input, context) => connections.status({ ...input, context })
+    }),
+    Object.freeze({
+      id: "connectors.connect",
+      kind: "command",
+      ...connectorsActionReach,
+      input: { schema: createSchema({ integrationId, verificationInput }) },
+      execute: (input, context) => connections.beginAuthorization({ ...input, context })
+    }),
+    Object.freeze({
+      id: "connectors.verifyClientCredentials",
+      kind: "command",
+      ...connectorsActionReach,
+      input: { schema: createSchema({ integrationId, verificationInput }) },
+      execute: (input, context) => connections.connectClientCredentials({ ...input, context })
+    }),
+    Object.freeze({
+      id: "connectors.verifyServiceAccount",
+      kind: "command",
+      ...connectorsActionReach,
+      input: { schema: createSchema({ integrationId, verificationInput }) },
+      execute: (input, context) => connections.connectServiceAccount({ ...input, context })
+    }),
+    Object.freeze({
+      id: "connectors.verifyApiKey",
+      kind: "command",
+      ...connectorsActionReach,
+      input: { schema: createSchema({ integrationId, verificationInput }) },
+      execute: (input, context) => connections.connectApiKey({ ...input, context })
+    }),
+    Object.freeze({
+      id: "connectors.verifyWithoutCredentials",
+      kind: "command",
+      ...connectorsActionReach,
+      input: { schema: createSchema({ integrationId, verificationInput }) },
+      execute: (input, context) => connections.connectWithoutCredentials({ ...input, context })
+    }),
+    Object.freeze({
+      id: "connectors.disconnect",
+      kind: "command",
+      ...connectorsActionReach,
+      input: { schema: createSchema({ integrationId }) },
+      execute: (input, context) => connections.disconnect({ ...input, context })
+    })
+  ]);
+}
+
+/** @param {import("./types.js").ConnectionServiceOptions} options */
 function createConnectorsFeature(options) {
   return defineFeature({
     id: "connectors.core",
@@ -11,24 +75,7 @@ function createConnectorsFeature(options) {
       return { connections: createConnectionService(options) };
     },
     actions({ connections }) {
-      const integrationId = { type: "string", required: true, minLength: 1, maxLength: 200 };
-      return [
-        ["status", "query", { integrationId }, (input, context) => connections.status({ ...input, context })],
-        ["connect", "command", { integrationId, verificationInput: { type: "object", additionalProperties: true } }, (input, context) => connections.beginAuthorization({ ...input, context })],
-        ["verifyClientCredentials", "command", { integrationId, verificationInput: { type: "object", additionalProperties: true } }, (input, context) => connections.connectClientCredentials({ ...input, context })],
-        ["verifyServiceAccount", "command", { integrationId, verificationInput: { type: "object", additionalProperties: true } }, (input, context) => connections.connectServiceAccount({ ...input, context })],
-        ["verifyApiKey", "command", { integrationId, verificationInput: { type: "object", additionalProperties: true } }, (input, context) => connections.connectApiKey({ ...input, context })],
-        ["verifyWithoutCredentials", "command", { integrationId, verificationInput: { type: "object", additionalProperties: true } }, (input, context) => connections.connectWithoutCredentials({ ...input, context })],
-        ["disconnect", "command", { integrationId }, (input, context) => connections.disconnect({ ...input, context })]
-      ].map(([name, kind, fields, execute]) => ({
-        id: `connectors.${name}`,
-        kind,
-        channels: ["api", "internal"],
-        surfaces: ["app"],
-        idempotency: "none",
-        input: { schema: createSchema(fields) },
-        execute
-      }));
+      return createConnectorsActions({ connections });
     }
   });
 }

package/src/server/connectionCredentials.js

@@ -0,0 +1,129 @@
+import * as oauth from "oauth4webapi";
+import { createHash } from "node:crypto";
+import { registrationClientAuthentication, registrationGrantType } from "../shared/configuration.js";
+import { ConnectorError } from "./errors.js";
+
+function validateCallbackUrl(value) {
+  let url;
+  try { url = new URL(value); } catch { /* reported below */ }
+  const localHttp = url?.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if (!url || (!localHttp && url.protocol !== "https:") || url.username || url.password || url.hash || url.search) {
+    throw new ConnectorError("connector_callback_invalid", "Configure an HTTPS callback URL, or a local development callback.", { messageCode: "connectors.connection.configureHttpsCallbackUrlLocal" });
+  }
+  return url.href;
+}
+
+/**
+ * The credentials an integration's bindings resolve to: its OAuth
+ * registration, API key, service-account credential or Env refresh token.
+ * @param {object} dependencies
+ * @param {Record<string, any>} dependencies.config The validated integration configuration.
+ * @param {import("./types.js").ResolveReference} dependencies.resolveReference
+ */
+function createConnectionCredentials({ config, resolveReference }) {
+  /**
+   * @param {Record<string, any>} integration
+   * @param {import("./providerRequests.js").ConnectionProvider} provider
+   */
+  async function registrationFor(integration, provider) {
+    const registration = config.registrations[integration.authentication.registrationRef];
+    if (registration?.source !== "own" || integration.authentication.method !== "oauth2" || !provider.oauth) {
+      throw new ConnectorError("connector_mode_unavailable", "This runtime does not yet support the selected credential mode.", { messageCode: "connectors.connection.runtimeDoesNotYetSupport" });
+    }
+    if (registration.clientId.trim() === "MISSING") {
+      throw new ConnectorError("connector_binding_missing", "The provider client ID is not configured.", { messageCode: "connectors.connection.providerClientIdNotConfigured" });
+    }
+    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.", { messageCode: "connectors.connection.providerNonPkceFlowRequires" });
+    }
+    let clientSecret;
+    let callback;
+    try {
+      if (tokenEndpointAuthMethod !== "none") {
+        clientSecret = await resolveReference(registration.clientSecretRef);
+        if (typeof clientSecret !== "string" || !clientSecret.trim() || clientSecret.trim() === "MISSING") throw new Error("Invalid client secret.");
+      }
+      if (grantType === "authorization_code") callback = await resolveReference(registration.callbackUrlRef);
+    } catch {
+      throw new ConnectorError("connector_binding_missing", "A required registration binding is missing.", { messageCode: "connectors.connection.requiredRegistrationBindingMissing" });
+    }
+    const callbackUrl = grantType === "authorization_code" ? validateCallbackUrl(callback) : undefined;
+    // readable-check: allow method-probe - optional operation: validateCallbackUrl is an optional hook of the provider definition
+    if (callbackUrl && typeof provider.validateCallbackUrl === "function" && provider.validateCallbackUrl(callbackUrl) !== true) {
+      throw new ConnectorError("connector_callback_invalid", "The callback URL does not meet this provider's requirements.", { messageCode: "connectors.connection.callbackUrlDoesNotMeet" });
+    }
+    let clientAuth = tokenEndpointAuthMethod === "none" ? oauth.None()
+      : tokenEndpointAuthMethod === "client_secret_basic" ? oauth.ClientSecretBasic(clientSecret) : oauth.ClientSecretPost(clientSecret);
+    if (tokenEndpointAuthMethod === "client_secret_basic" && provider.oauthBasicEncoding === "raw") {
+      clientAuth = (_as, client, _body, headers) => {
+        headers.set("authorization", `Basic ${Buffer.from(`${client.client_id}:${clientSecret}`).toString("base64")}`);
+      };
+    }
+    return {
+      // readable-check: allow method-probe - data: a provider definition gives oauth as metadata or as a function of the settings
+      oauth: typeof provider.oauth === "function" ? provider.oauth(integration.settings) : provider.oauth,
+      // readable-check: allow method-probe - data: a provider definition gives oauthResource as a value or as a function of the settings
+      resource: typeof provider.oauthResource === "function" ? provider.oauthResource(integration.settings) : provider.oauthResource,
+      client: { client_id: registration.clientId },
+      clientAuth: provider.oauthClientIdParameter ? (as, client, body, headers) => {
+        clientAuth(as, client, body, headers);
+        body.set(provider.oauthClientIdParameter, client.client_id);
+        body.delete("client_id");
+      } : clientAuth,
+      tokenEndpointAuthMethod,
+      grantType,
+      callbackUrl,
+      registrationRef: integration.authentication.registrationRef
+    };
+  }
+
+  /**
+   * @param {Record<string, any>} integration
+   * @param {import("./providerRequests.js").ConnectionProvider} provider
+   */
+  async function apiKeyFor(integration, provider) {
+    if (!integration.authentication.secretRef && provider.apiKeySecretOptional) return "";
+    try {
+      const value = await resolveReference(integration.authentication.secretRef);
+      if (typeof value !== "string" || (!provider.apiKeySecretOptional && !value.trim()) || value.trim() === "MISSING" || /[\r\n]/u.test(value)) throw new Error("Invalid key.");
+      return value;
+    } catch {
+      throw new ConnectorError("connector_binding_missing", "The API key binding is missing or invalid.", { messageCode: "connectors.connection.apiKeyBindingMissingInvalid" });
+    }
+  }
+
+  async function serviceAccountCredentialFor(integration) {
+    try {
+      const credential = await resolveReference(integration.authentication.secretRef);
+      if (typeof credential !== "string" || !credential.trim() || credential.trim() === "MISSING" || credential.length > 65_536 || credential.includes("\0")) throw new Error("Invalid credential.");
+      return { credential, fingerprint: createHash("sha256").update(credential).digest("hex") };
+    } catch {
+      throw new ConnectorError("connector_binding_missing", "The service-account credential binding is missing or invalid.", { messageCode: "connectors.connection.serviceAccountCredentialBindingMissing" });
+    }
+  }
+
+  // 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.", { messageCode: "connectors.connection.refreshTokenBindingMissingInvalid" });
+    }
+  }
+
+  return Object.freeze({
+    registrationFor,
+    apiKeyFor,
+    serviceAccountCredentialFor,
+    envRefreshTokenFor
+  });
+}
+
+export { createConnectionCredentials };