@jskit-ai/connectors-core 0.1.60 → 0.1.62

package/package.json

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

package/src/server/connectionService.js

@@ -13,10 +13,13 @@ 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.";
+
 function validateCallbackUrl(value) {
   let url;
   try { url = new URL(value); } catch { /* reported below */ }
@@ -166,6 +169,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.");
@@ -380,6 +415,9 @@ 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 || {});
     const registration = await registrationFor(integration, provider);
@@ -544,7 +582,12 @@ function createConnectionService({
     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 (seed && !envSeedIsCurrent(connection, seed, registration)) {
+        connection = envSeededConnection(integrationId, integration, provider, registration, seed);
+        await save(connection);
+      }
       if (!connection || connection.status !== "connected" || connection.provider !== provider.id ||
         (connection.method || "oauth2") !== integration.authentication.method ||
         !isDeepStrictEqual(connection.settings || {}, integration.settings || {}) ||
@@ -597,8 +640,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 };
       }
@@ -611,7 +657,7 @@ function createConnectionService({
     const { owner, integration, provider } = await access(context, integrationId, "status");
     const registration = config.registrations[integration.authentication.registrationRef];
     return store.withConnection({ owner, integrationId }, async ({ connection }) => {
-      if (connection && (connection.provider !== integration.provider ||
+      if (connection && !integration.authentication.refreshTokenRef && (connection.provider !== integration.provider ||
         (connection.method || "oauth2") !== integration.authentication.method ||
         !isDeepStrictEqual(connection.settings || {}, integration.settings || {}) ||
         (["api-key", "service-account"].includes(integration.authentication.method) && connection.secretRef !== integration.authentication.secretRef) ||
@@ -627,6 +673,13 @@ function createConnectionService({
         if (integration.authentication.method === "oauth2") {
           const resolved = await registrationFor(integration, provider);
           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 && provider.refreshRequiresRedirectUri && resolved.grantType === "authorization_code" &&
               connection.callbackUrl !== resolved.callbackUrl) {
             return publicConnection({ ...connection, status: "reconnect-required" });
@@ -647,7 +700,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/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({
@@ -117,11 +118,19 @@ function validateIntegrationConfiguration(input, { providers = [], allowUnknownP
     const provider = definitions.get(integration.provider);
     const registration = config.registrations[auth.registrationRef];
     const grantType = registration?.grantType || "authorization_code";
+    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.";
       }

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" });
+});