@jskit-ai/connectors-core 0.2.14 → 0.2.15

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## Unreleased
+
+- `@jskit-ai/database-runtime` and `@jskit-ai/resource-runtime` are optional peer dependencies, as they are of assistant-runtime, instead of dependencies: an app without a database installs, composes and starts the package without them, where installing them made boot refuse it for want of a database driver. An app that uses its knex connection store (`./server/storage`) has them through its database.
+- `createKnexConnectionStore` owns the connector tables through resource-runtime's `createStandaloneResources`, with the connection store's declared system scope, instead of building a resource runtime and host of its own.
+- `connectors.core` without a store requires `connectors.store` again, with a hint, so the kernel's startup error names the missing capability and says to register `createConnectionStoreFeature({ protection })` or pass `createConnectorsFeature({ store })`, instead of a check in its own setup.
+- The connection store locks or creates each connection row with its handle's `lockOrCreate`, in place of a helper of its own with the same behaviour.
+- `connectors.core` without a `store` and without `createConnectionStoreFeature({ protection })` fails at startup naming that feature and where to register it, where the runtime only said a capability was missing; `createConnectionService` given no store names the same fix.
+- `withConnection` creates a missing connection row inside the work's own transaction (an insert that skips an existing id), so work that fails leaves no row behind. Two first uses of one connection that collide on that insert before either work runs (a deadlock on MySQL's and MariaDB's gap locks, a duplicate key elsewhere) run the loser again, up to three times; work that has started never runs again. An existing row costs one locking read, where the store read it once outside the transaction and again under the lock.
+- `pruneExpiredAttempts` counts the deleted attempts in the database instead of reading their ids.
+
 ## 0.2.0 - 2026-10-29
 
 - Translation ready: every user-visible text is a message key with its English in `locales/en.json`, so an app translates it by supplying translation files only. With no translations, texts and behaviour are unchanged. See the guide "Translating a JSKIT app".

package/README.md

@@ -442,8 +442,17 @@ an old key before those rows are rewritten makes them unreadable. Applications
 with an existing vault can instead provide compatible `seal(value, binding)`
 and `open(ciphertext, binding)` methods.
 
-The Knex store uses the application's own Knex client and its `transaction()`;
-editing portable configuration does not install or activate a database provider.
+The Knex store uses the application's own Knex client; editing portable
+configuration does not install or activate a database provider. It owns the
+connector tables as table resources and reads and writes them through their
+handles. Code outside a JSKIT server, such as a command-line script, uses
+`createKnexConnectionStore`. A JSKIT application instead adds
+`createConnectionStoreFeature({ protection })`, also from
+`@jskit-ai/connectors-core/server/storage`: it owns the tables through the
+application's `runtime.resources` and provides the store as `connectors.store`,
+which `createConnectorsFeature(options)` uses when `options.store` is absent. An
+application that passes its own `store` (the file store, for example) needs no
+database.
 
 The package declares its authoritative migration directory in `package.json`.
 Use the normal app-owned `knexfile.js` and migration scripts described by the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/connectors-core",
-  "version": "0.2.14",
+  "version": "0.2.15",
   "description": "Portable integration configuration and server-side account connection runtime.",
   "type": "module",
   "scripts": {
@@ -15,6 +15,7 @@
     "./locales/en.json": "./locales/en.json"
   },
   "dependencies": {
+    "@jskit-ai/resource-core": "0.1.205",
     "jose": "^6.1.3",
     "json-rest-schema": "^1.0.17",
     "oauth4webapi": "3.8.8",
@@ -55,7 +56,17 @@
     }
   },
   "peerDependencies": {
-    "@jskit-ai/http-runtime": "0.2.13",
-    "@jskit-ai/kernel": "0.2.13"
+    "@jskit-ai/database-runtime": "0.1.263",
+    "@jskit-ai/http-runtime": "0.2.14",
+    "@jskit-ai/kernel": "0.2.14",
+    "@jskit-ai/resource-runtime": "0.2.12"
+  },
+  "peerDependenciesMeta": {
+    "@jskit-ai/database-runtime": {
+      "optional": true
+    },
+    "@jskit-ai/resource-runtime": {
+      "optional": true
+    }
   }
 }

package/src/server/ConnectionStoreFeature.js

@@ -0,0 +1,34 @@
+import { defineFeature } from "@jskit-ai/kernel/server/features";
+import { createConnectionStore } from "./connectionStore.js";
+import { CONNECTOR_TABLES } from "./connectorResources.js";
+
+const CONNECTION_STORE_FEATURE = "connectors.storage";
+const CONNECTION_STORE_SYSTEM_SCOPE = "connector rows are keyed by their owner's application and subject and their integration, which is their scope, not by a workspace or user";
+
+/**
+ * The owner of the connector tables in a JSKIT application: it provides the connection store on their handles as
+ * `connectors.store`, which createConnectorsFeature() uses when it is given no store. An application that keeps
+ * connections in files passes createFileConnectionStore() instead and leaves this feature out.
+ * @param {{ protection: import("./types.js").CredentialProtection }} options
+ */
+function createConnectionStoreFeature({ protection }) {
+  return defineFeature({
+    id: CONNECTION_STORE_FEATURE,
+    domain: "connectors",
+    owns: CONNECTOR_TABLES,
+    systemScope: CONNECTION_STORE_SYSTEM_SCOPE,
+    provides: {
+      store: "connectors.store"
+    },
+    /**
+     * @param {object} dependencies
+     * @param {Record<string, import("@jskit-ai/resource-runtime/server/types").ResourceHandle>} dependencies.resources
+     * @param {(reason: string) => import("@jskit-ai/resource-runtime/server/types").SystemContext} dependencies.systemContext
+     */
+    setup({ resources, systemContext }) {
+      return { store: createConnectionStore({ resources, systemContext, protection }) };
+    }
+  });
+}
+
+export { CONNECTION_STORE_FEATURE, CONNECTION_STORE_SYSTEM_SCOPE, createConnectionStoreFeature };

package/src/server/ConnectorsFeature.js

@@ -65,14 +65,24 @@ function createConnectorsActions({ connections }) {
   ]);
 }
 
-/** @param {import("./types.js").ConnectionServiceOptions} options */
+/**
+ * The `connectors.core` feature. Given no `store`, it keeps connections in the `connectors.store` capability, which
+ * createConnectionStoreFeature() provides on the connector tables; without that feature the app fails at startup, naming it.
+ * @param {Omit<import("./types.js").ConnectionServiceOptions, "store"> & { store?: import("./types.js").ConnectionStore }} options
+ */
 function createConnectorsFeature(options) {
   return defineFeature({
     id: "connectors.core",
     domain: "connectors",
+    requires: options.store ? {} : { store: "connectors.store" },
+    hints: options.store ? {} : {
+      "connectors.store": "Register createConnectionStoreFeature({ protection }) from @jskit-ai/connectors-core/server/storage " +
+        "in your server providers, or pass createConnectorsFeature({ store })."
+    },
     provides: { connections: "connectors.core" },
-    setup() {
-      return { connections: createConnectionService(options) };
+    /** @param {{ store?: import("./types.js").ConnectionStore }} dependencies */
+    setup({ store = options.store }) {
+      return { connections: createConnectionService({ ...options, store }) };
     },
     actions({ connections }) {
       return createConnectorsActions({ connections });

package/src/server/connectionService.js

@@ -82,7 +82,13 @@ function createConnectionService({
     throw new TypeError("Connections require application authorization and reference resolution.");
   }
   // readable-check: allow method-probe - input validation: the application passes its own connection store
-  if (typeof store?.withConnection !== "function") throw new TypeError("Connection storage requires withConnection().");
+  if (typeof store?.withConnection !== "function") {
+    throw new TypeError(
+      "Connections require a connection store with withConnection(): register createConnectionStoreFeature({ protection }) from " +
+      "@jskit-ai/connectors-core/server/storage in your server providers and pass its connectors.store, or pass " +
+      "createFileConnectionStore() or createKnexConnectionStore() outside a JSKIT server."
+    );
+  }
   const connectionCredentials = createConnectionCredentials({ config, resolveReference });
   const providerRequests = createProviderRequests({ fetchImpl, now, resolveReference });
 

package/src/server/connectionStore.js

@@ -0,0 +1,86 @@
+import { createHash } from "node:crypto";
+
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+
+/**
+ * The application's credential protection, checked before it is used.
+ * @param {import("./types.js").CredentialProtection} protection
+ */
+function requireProtection(protection) {
+  // 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.");
+  }
+  return protection;
+}
+
+/**
+ * Connections kept encrypted in the connector tables, on their table resources' handles, each locked in a transaction
+ * while it is used. Every call works in a system context, because a row's scope is its key.
+ * @param {object} dependencies
+ * @param {Record<string, import("@jskit-ai/resource-runtime/server/types").ResourceHandle>} dependencies.resources The handles of CONNECTOR_TABLES.
+ * @param {(reason: string) => import("@jskit-ai/resource-runtime/server/types").SystemContext} dependencies.systemContext
+ * @param {import("./types.js").CredentialProtection} dependencies.protection
+ */
+function createConnectionStore({ resources, systemContext, protection }) {
+  requireProtection(protection);
+  const { connectorConnections: connections, connectorAuthorizationAttempts: attempts } = resources;
+  const connectionOptions = Object.freeze({ context: systemContext("a connection and its attempts are read and changed by their owner and integration key") });
+  const pruneOptions = Object.freeze({ context: systemContext("maintenance prunes every connection's expired authorization attempts") });
+
+  async function withConnection({ owner, integrationId }, work) {
+    const connectionKey = hash(JSON.stringify([owner.applicationId, owner.subjectId, integrationId]));
+    const connectionBinding = `connection:${connectionKey}`;
+    // Retain this row on disconnect so other processes continue to lock the same identity.
+    return connections.lockOrCreate({ id: connectionKey, payload: null }, connectionOptions, async (row, txOptions) => {
+      const writeOptions = { ...txOptions, returning: "none" };
+      return work({
+        connection: row.payload ? await protection.open(row.payload, connectionBinding) : null,
+        save: async (connection) => {
+          const payload = await protection.seal(connection, connectionBinding);
+          await connections.patch(connectionKey, { payload }, writeOptions);
+        },
+        remove: async () => {
+          await connections.patch(connectionKey, { payload: null }, writeOptions);
+          await attempts.deleteWhere({ connectionKey }, txOptions);
+        },
+        putAttempt: async (attempt) => {
+          const attemptKey = hash(attempt.state);
+          await attempts.create({
+            id: attemptKey,
+            connectionKey,
+            expiresAt: attempt.expiresAt,
+            payload: await protection.seal(attempt, `attempt:${connectionKey}:${attemptKey}`)
+          }, writeOptions);
+        },
+        latestAttempt: async ({ after }) => {
+          const { records: [attempt] } = await attempts.query({
+            filters: { connectionKey, expiresAfter: after },
+            sort: "-expiresAt",
+            page: { size: 1 }
+          }, txOptions);
+          return attempt ? protection.open(attempt.payload, `attempt:${connectionKey}:${attempt.id}`) : null;
+        },
+        consumeAttempt: async (state) => {
+          const attemptKey = hash(state);
+          // A locking read sees an attempt another transaction consumed while this one waited for the connection.
+          const [attempt] = await attempts.lockMany([attemptKey], { ...txOptions, missing: "skip" });
+          if (attempt?.connectionKey !== connectionKey) return null;
+          await attempts.delete(attemptKey, { ...txOptions, missing: "skip" });
+          return protection.open(attempt.payload, `attempt:${connectionKey}:${attemptKey}`);
+        }
+      });
+    });
+  }
+
+  async function pruneExpiredAttempts({ before = Date.now() } = {}) {
+    return attempts.deleteWhere({ expiredBy: before }, { ...pruneOptions, returning: "count" });
+  }
+
+  return Object.freeze({
+    withConnection,
+    pruneExpiredAttempts
+  });
+}
+
+export { createConnectionStore, requireProtection };

package/src/server/connectorResources.js

@@ -0,0 +1,48 @@
+import { defineTableResource } from "@jskit-ai/resource-core/shared/tableResource";
+import { normalizeOpaqueId } from "@jskit-ai/kernel/shared/support/normalize";
+
+// The connector tables. A connection is keyed by a hash of its owner's application and subject and its integration,
+// and an attempt by a hash of its state, not by a workspace or user column: the key is the row's scope, so the tables
+// are public to their owner feature, which reaches them only through keys it computes from a caller's owner and slot.
+
+// A hash the store computes; ciphertext is kept exactly as written.
+const key = (column) => Object.freeze({ type: "string", primary: true, required: true, storage: { column } });
+const ciphertext = Object.freeze({ type: "string", noTrim: true });
+
+// One owner's connection to one integration: its sealed state, or null while it is disconnected.
+const connectorConnectionResource = defineTableResource({
+  name: "connectorConnections",
+  tableName: "connector_connections",
+  ownership: "public",
+  idProperty: "connection_key",
+  schema: {
+    id: key("connection_key"),
+    payload: { ...ciphertext, nullable: true }
+  }
+});
+
+// A pending authorization of one connection, sealed, until it is consumed or expires.
+const connectorAuthorizationAttemptResource = defineTableResource({
+  name: "connectorAuthorizationAttempts",
+  tableName: "connector_authorization_attempts",
+  ownership: "public",
+  idProperty: "attempt_key",
+  sortableFields: ["expiresAt"],
+  schema: {
+    id: key("attempt_key"),
+    connectionKey: { type: "string", required: true, storage: { column: "connection_key" } },
+    expiresAt: { type: "integer", required: true, storage: { column: "expires_at" } },
+    payload: { ...ciphertext, required: true }
+  },
+  searchSchema: {
+    connectionKey: { type: "string", actualField: "connectionKey" },
+    expiresAfter: { type: "number", actualField: "expiresAt", filterOperator: ">" },
+    expiredBy: { type: "number", actualField: "expiresAt", filterOperator: "<=" }
+  }
+});
+
+// The feature's owns entries: each key is an opaque hash, not a numeric id.
+const CONNECTOR_TABLES = Object.freeze([connectorConnectionResource, connectorAuthorizationAttemptResource]
+  .map((resource) => Object.freeze({ resource, normalizeId: normalizeOpaqueId })));
+
+export { CONNECTOR_TABLES, connectorAuthorizationAttemptResource, connectorConnectionResource };

package/src/server/knexConnectionStore.js

@@ -1,9 +1,14 @@
-import { createHash } from "node:crypto";
-
-const hash = (value) => createHash("sha256").update(value).digest("hex");
+// readable-check: allow no-direct-knex - infrastructure: a command-line script's connection store on the application's Knex
+import { createStandaloneResources } from "@jskit-ai/resource-runtime/server";
+import { CONNECTION_STORE_FEATURE, CONNECTION_STORE_SYSTEM_SCOPE } from "./ConnectionStoreFeature.js";
+import { createConnectionStore, requireProtection } from "./connectionStore.js";
+import { CONNECTOR_TABLES } from "./connectorResources.js";
 
 /**
- * Connections kept encrypted in the connector tables, each locked in a transaction while it is used.
+ * Connections kept encrypted in the connector tables, each locked in a transaction while it is used, for code outside
+ * a JSKIT server such as a command-line script: the store owns the connector tables through standalone resources on
+ * the application's Knex and answers what createConnectionStoreFeature()'s store answers. A JSKIT application
+ * uses that feature instead, so its tables have one owner.
  * @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
@@ -13,55 +18,31 @@ function createKnexConnectionStore({ knex, protection }) {
   if (typeof knex !== "function" || typeof knex.transaction !== "function") {
     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.");
+  requireProtection(protection);
+  let ready = null;
+  async function compose() {
+    const { resources, systemContext } = await createStandaloneResources({
+      knex,
+      feature: CONNECTION_STORE_FEATURE,
+      owns: CONNECTOR_TABLES,
+      systemScope: CONNECTION_STORE_SYSTEM_SCOPE
+    });
+    return createConnectionStore({ resources, systemContext, protection });
   }
-  async function withConnection({ owner, integrationId }, work) {
-    const connectionKey = hash(JSON.stringify([owner.applicationId, owner.subjectId, integrationId]));
-    const connectionBinding = `connection:${connectionKey}`;
-    return knex.transaction(async (trx) => {
-      // Retain this row on disconnect so other processes continue to lock the same identity.
-      await trx("connector_connections").insert({ connection_key: connectionKey })
-        .onConflict("connection_key").merge({ connection_key: connectionKey });
-      const row = await trx("connector_connections").where({ connection_key: connectionKey }).forUpdate().first();
-      return work({
-        connection: row.payload ? await protection.open(row.payload, connectionBinding) : null,
-        save: async (connection) => {
-          const payload = await protection.seal(connection, connectionBinding);
-          await trx("connector_connections").where({ connection_key: connectionKey }).update({ payload });
-        },
-        remove: async () => {
-          await trx("connector_connections").where({ connection_key: connectionKey }).update({ payload: null });
-          await trx("connector_authorization_attempts").where({ connection_key: connectionKey }).delete();
-        },
-        putAttempt: async (attempt) => {
-          const attemptKey = hash(attempt.state);
-          await trx("connector_authorization_attempts").insert({
-            attempt_key: attemptKey, connection_key: connectionKey, expires_at: attempt.expiresAt,
-            payload: await protection.seal(attempt, `attempt:${connectionKey}:${attemptKey}`)
-          });
-        },
-        latestAttempt: async ({ after }) => {
-          const attempt = await trx("connector_authorization_attempts")
-            .where({ connection_key: connectionKey }).where("expires_at", ">", after)
-            .orderBy("expires_at", "desc").first();
-          return attempt ? protection.open(attempt.payload, `attempt:${connectionKey}:${attempt.attempt_key}`) : null;
-        },
-        consumeAttempt: async (state) => {
-          const attemptKey = hash(state);
-          const where = { attempt_key: attemptKey, connection_key: connectionKey };
-          const attempt = await trx("connector_authorization_attempts").where(where).first();
-          if (!attempt) return null;
-          await trx("connector_authorization_attempts").where(where).delete();
-          return protection.open(attempt.payload, `attempt:${connectionKey}:${attemptKey}`);
-        }
-      });
+  // The handles are built once, on the first call; a failed build is tried again on the next one.
+  function store() {
+    ready ||= compose().catch((error) => {
+      ready = null;
+      throw error;
     });
+    return ready;
   }
 
-  async function pruneExpiredAttempts({ before = Date.now() } = {}) {
-    return knex("connector_authorization_attempts").where("expires_at", "<=", before).delete();
+  async function withConnection(slot, work) {
+    return (await store()).withConnection(slot, work);
+  }
+  async function pruneExpiredAttempts(options) {
+    return (await store()).pruneExpiredAttempts(options);
   }
 
   return Object.freeze({

package/src/server/storage.js

@@ -1,2 +1,3 @@
 export { createCredentialProtection } from "./credentialProtection.js";
+export { createConnectionStoreFeature } from "./ConnectionStoreFeature.js";
 export { createKnexConnectionStore } from "./knexConnectionStore.js";

package/test/connectionService.test.js

@@ -103,6 +103,22 @@ test("result validation sees the request its operation built and rejects a misma
   await assert.rejects(service.invoke({ ...input, operation: "connection.check" }), { code: "connector_response_invalid", statusCode: 502 });
 });
 
+test("connections without a store fail at startup, naming the feature to register", async () => {
+  const options = {
+    configuration: databaseConfiguration({ method: "none" }), providers: [clickhouseProvider],
+    authorize: async (context) => context, resolveReference: async () => ""
+  };
+  // The kernel's startup error names the missing capability and adds the feature's hint.
+  assert.throws(() => createCapabilityRuntime({ inputs: { "runtime.logger": silentLogger }, providers: [EventProvider, ActionProvider, createConnectorsFeature(options)] }), {
+    message: 'Provider "connectors.core" requires missing capability "connectors.store". Register createConnectionStoreFeature({ protection }) ' +
+      "from @jskit-ai/connectors-core/server/storage in your server providers, or pass createConnectorsFeature({ store })."
+  });
+  assert.throws(() => createConnectionService({ ...options, store: {} }), {
+    name: "TypeError",
+    message: /^Connections require a connection store with withConnection\(\): register createConnectionStoreFeature\(\{ protection \}\) from @jskit-ai\/connectors-core\/server\/storage/u
+  });
+});
+
 test("the ordinary credential-free Feature action verifies without resolving references", async () => {
   const contexts = [];
   let actions;

package/test/connectionStoreFeature.test.js

@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import { randomBytes } from "node:crypto";
+import test from "node:test";
+import knexLib from "knex";
+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 { createCapabilityRuntime, defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import { createTestResourceRuntime } from "@jskit-ai/resource-runtime/test";
+import migration from "../migrations/connectors_core_initial.cjs";
+import { createConnectionStoreFeature, createCredentialProtection } from "../src/server/storage.js";
+
+const owner = Object.freeze({ applicationId: "app", subjectId: "user-1" });
+
+test("createConnectionStoreFeature owns the connector tables and provides the store on their handles as connectors.store", async (t) => {
+  const knex = knexLib({ client: "better-sqlite3", connection: { filename: ":memory:" }, useNullAsDefault: true, pool: { min: 1, max: 1 } });
+  t.after(() => knex.destroy());
+  await migration.up(knex);
+  const resources = await createTestResourceRuntime({ knex });
+  const protection = createCredentialProtection({ keys: { current: randomBytes(32) }, activeKeyId: "current" });
+  let store = null;
+  const runtime = createCapabilityRuntime({
+    inputs: { "runtime.logger": silentLogger },
+    providers: [
+      EventProvider,
+      ActionProvider,
+      defineProvider({ id: "test.resources", provides: { resources: "runtime.resources" }, setup: () => ({ resources }) }),
+      createConnectionStoreFeature({ protection }),
+      defineProvider({ id: "test.connections", requires: { connections: "connectors.store" }, setup({ connections }) { store = connections; } })
+    ]
+  });
+  await runtime.start();
+  t.after(() => runtime.shutdown());
+
+  assert.deepEqual(resources.ownedTables().map(({ tableName, featureId }) => [tableName, featureId]), [
+    ["connector_connections", "connectors.storage"],
+    ["connector_authorization_attempts", "connectors.storage"]
+  ]);
+  const slot = { owner, integrationId: "calendar" };
+  await store.withConnection(slot, async ({ connection, save, putAttempt }) => {
+    assert.equal(connection, null);
+    await save({ token: "t1" });
+    await putAttempt({ state: "s1", expiresAt: 2_000 });
+  });
+  assert.deepEqual(await store.withConnection(slot, async ({ connection, latestAttempt, consumeAttempt }) => [
+    connection,
+    (await latestAttempt({ after: 1_000 }))?.state,
+    (await consumeAttempt("s1"))?.state,
+    await consumeAttempt("s1")
+  ]), [{ token: "t1" }, "s1", "s1", null]);
+  await store.withConnection(slot, ({ putAttempt }) => putAttempt({ state: "s2", expiresAt: 3_000 }));
+  assert.equal(await store.pruneExpiredAttempts({ before: 3_000 }), 1);
+});

package/test/knexConnectionStore.mysql.test.js

@@ -0,0 +1,199 @@
+import assert from "node:assert/strict";
+import { randomBytes } from "node:crypto";
+import test from "node:test";
+import knexLib from "knex";
+import { requireTestDatabase } from "@jskit-ai/database-runtime/server/testDatabases";
+import migration from "../migrations/connectors_core_initial.cjs";
+import { createCredentialProtection, createKnexConnectionStore } from "../src/server/storage.js";
+
+// The SQL connection store's behaviour on MariaDB, through withConnection and pruneExpiredAttempts, pinned before the
+// store moves onto table resources. knexConnectionStore.test.js covers encryption, reopening through another pool,
+// concurrent saves, rollback of a save, owner isolation of credentials and consent attempts when
+// CONNECTORS_TEST_DATABASE_URL is set (it skips without it); this file adds what it leaves open: the values each call
+// answers, which parts of a scope count, rollback of a disconnect and of a failed seal, attempt keys, the newest
+// attempt, and pruning's count and boundary.
+
+// The runtime's own MySQL connection settings (database-runtime's resolveKnexConnectionFromEnvironment).
+const RUNTIME_MYSQL = Object.freeze({ supportBigNumbers: true, bigNumberStrings: true, dateStrings: ["DATE"], timezone: "Z" });
+
+/** A migrated database of the test's own, beside TEST_DB_NAME, dropped after the test. */
+async function ownDatabase(context, suffix) {
+  const name = `${requireTestDatabase(process.env)}_${suffix}`;
+  const server = { host: process.env.DB_HOST, port: Number(process.env.DB_PORT) || 3306, user: process.env.DB_USER, password: process.env.DB_PASSWORD };
+  const admin = knexLib({ client: "mysql2", connection: server, pool: { min: 0, max: 1 } });
+  await admin.raw("DROP DATABASE IF EXISTS ??", [name]);
+  await admin.raw("CREATE DATABASE ??", [name]);
+  const knex = knexLib({ client: "mysql2", connection: { ...server, database: name, ...RUNTIME_MYSQL }, pool: { min: 0, max: 4 } });
+  context.after(async () => {
+    await knex.destroy();
+    await admin.raw("DROP DATABASE IF EXISTS ??", [name]);
+    await admin.destroy();
+  });
+  await migration.up(knex);
+  return knex;
+}
+
+const protection = createCredentialProtection({ keys: { test: randomBytes(32) }, activeKeyId: "test" });
+const owner = Object.freeze({ applicationId: "test-application", subjectId: "user-a" });
+const scope = Object.freeze({ owner, integrationId: "calendar" });
+const read = (store, at) => store.withConnection(at, async ({ connection }) => connection);
+
+test("the store needs the application's Knex and credential protection, and answers what each call's work returns", async (context) => {
+  requireTestDatabase(process.env);
+  const knex = await ownDatabase(context, "da_conn_values");
+  assert.throws(() => createKnexConnectionStore({ knex: {}, protection }), { name: "TypeError", message: "createKnexConnectionStore requires the application's Knex instance." });
+  assert.throws(() => createKnexConnectionStore({ knex }), { name: "TypeError", message: "Connector storage requires credential protection." });
+  assert.throws(() => createKnexConnectionStore({ knex, protection: { seal: async () => "" } }), { name: "TypeError", message: "Connector storage requires credential protection." });
+  const store = createKnexConnectionStore({ knex, protection });
+  assert.ok(Object.isFrozen(store));
+  assert.deepEqual(Object.keys(store), ["withConnection", "pruneExpiredAttempts"]);
+
+  const answered = await store.withConnection(scope, async (handle) => {
+    assert.deepEqual(Object.keys(handle), ["connection", "save", "remove", "putAttempt", "latestAttempt", "consumeAttempt"]);
+    assert.equal(handle.connection, null, "a new identity has no connection");
+    assert.equal(await handle.save({ status: "connected", tokens: { accessToken: "a" }, at: new Date(Date.UTC(2026, 0, 1)) }), undefined);
+    assert.equal(handle.connection, null, "the handle keeps the connection it opened with");
+    assert.equal(await handle.putAttempt({ state: "state-1", expiresAt: Date.now() + 60_000 }), undefined);
+    return { done: true };
+  });
+  assert.deepEqual(answered, { done: true });
+  assert.deepEqual(await read(store, scope), { status: "connected", tokens: { accessToken: "a" }, at: "2026-01-01T00:00:00.000Z" }, "kept as JSON");
+  assert.equal(await store.withConnection(scope, async ({ remove }) => remove()), undefined);
+  assert.equal(await read(store, scope), null, "a disconnect leaves no connection");
+  assert.equal(await store.withConnection(scope, ({ consumeAttempt }) => consumeAttempt("state-1")), null, "and no attempts");
+  await store.withConnection(scope, ({ save }) => save({ status: "reconnected" }));
+  assert.deepEqual(await read(store, scope), { status: "reconnected" }, "an identity connects again after a disconnect");
+});
+
+test("a connection is the owner's application, subject and integration, and nothing else in the scope", async (context) => {
+  requireTestDatabase(process.env);
+  const store = createKnexConnectionStore({ knex: await ownDatabase(context, "da_conn_scope"), protection });
+  await store.withConnection(scope, ({ save }) => save({ account: "calendar-a" }));
+  await store.withConnection({ owner, integrationId: "mail" }, ({ save }) => save({ account: "mail-a" }));
+
+  assert.deepEqual(await read(store, scope), { account: "calendar-a" });
+  assert.deepEqual(await read(store, { owner, integrationId: "mail" }), { account: "mail-a" }, "each integration of an owner is its own");
+  assert.equal(await read(store, { owner: { ...owner, subjectId: "user-b" }, integrationId: "calendar" }), null);
+  assert.equal(await read(store, { owner: { ...owner, applicationId: "other-application" }, integrationId: "calendar" }), null);
+  // Fields of the owner other than applicationId and subjectId do not separate connections.
+  assert.deepEqual(await read(store, { owner: { ...owner, workspaceId: "workspace-9", role: "admin" }, integrationId: "calendar" }), { account: "calendar-a" });
+  assert.deepEqual(await read(store, { owner: { subjectId: owner.subjectId, applicationId: owner.applicationId }, integrationId: "calendar" }), { account: "calendar-a" });
+});
+
+test("a failed disconnect or a failed seal keeps the connection and its attempts as they were", async (context) => {
+  requireTestDatabase(process.env);
+  const knex = await ownDatabase(context, "da_conn_rollback");
+  const store = createKnexConnectionStore({ knex, protection });
+  const attempt = { state: "pending-state", codeVerifier: "verifier", expiresAt: Date.now() + 60_000 };
+  await store.withConnection(scope, async ({ save, putAttempt }) => {
+    await save({ version: 1 });
+    await putAttempt(attempt);
+  });
+
+  const failure = new Error("revocation failed");
+  await assert.rejects(store.withConnection(scope, async ({ remove }) => {
+    await remove();
+    throw failure;
+  }), (error) => error === failure);
+  assert.deepEqual(await read(store, scope), { version: 1 });
+  assert.deepEqual(await store.withConnection(scope, ({ latestAttempt }) => latestAttempt({ after: Date.now() })), attempt);
+
+  const sealFailure = new Error("vault unavailable");
+  const brokenWriter = createKnexConnectionStore({ knex, protection: { ...protection, seal: async () => { throw sealFailure; } } });
+  await assert.rejects(brokenWriter.withConnection(scope, async ({ save }) => {
+    await save({ version: 2 });
+  }), (error) => error === sealFailure);
+  assert.deepEqual(await read(store, scope), { version: 1 });
+  assert.deepEqual(await store.withConnection(scope, ({ consumeAttempt }) => consumeAttempt(attempt.state)), attempt);
+
+  // A connection whose first work fails leaves no row: its creation rolls back with the work.
+  const [{ rows }] = await knex("connector_connections").count({ rows: "*" });
+  await assert.rejects(store.withConnection({ ...scope, integrationId: "never-kept" }, async ({ save }) => {
+    await save({ version: 1 });
+    throw failure;
+  }), (error) => error === failure);
+  assert.deepEqual(await knex("connector_connections").count({ rows: "*" }), [{ rows }]);
+});
+
+test("first uses of new connections at once each create their row once and run their work once", { timeout: 20_000 }, async (context) => {
+  requireTestDatabase(process.env);
+  const knex = await ownDatabase(context, "da_conn_race");
+  const store = createKnexConnectionStore({ knex, protection });
+  const slots = ["one", "two", "three"].map((integrationId) => ({ ...scope, integrationId }));
+  let runs = 0;
+  const saved = await Promise.all(slots.flatMap((slot) => [1, 2].map(() => store.withConnection(slot, async ({ connection, save }) => {
+    runs += 1;
+    const version = (connection?.version ?? 0) + 1;
+    await save({ version });
+    return version;
+  }))));
+  assert.equal(runs, 6, "each work ran once");
+  for (const [index, slot] of slots.entries()) {
+    assert.deepEqual(saved.slice(index * 2, index * 2 + 2).sort(), [1, 2], slot.integrationId);
+    assert.deepEqual(await read(store, slot), { version: 2 }, slot.integrationId);
+  }
+  const [{ rows }] = await knex("connector_connections").count({ rows: "*" });
+  assert.equal(Number(rows), 3);
+});
+
+test("an attempt is keyed by its state alone, the newest live one is answered, and consuming takes it once", async (context) => {
+  requireTestDatabase(process.env);
+  const store = createKnexConnectionStore({ knex: await ownDatabase(context, "da_conn_attempts"), protection });
+  const now = Date.now();
+  const older = { state: "older", expiresAt: now + 10_000, owner, integrationId: "calendar" };
+  const newer = { state: "newer", expiresAt: now + 20_000, owner, integrationId: "calendar" };
+  await store.withConnection(scope, async ({ putAttempt, latestAttempt }) => {
+    assert.equal(await latestAttempt({ after: now }), null);
+    await putAttempt(newer);
+    await putAttempt(older);
+    assert.deepEqual(await latestAttempt({ after: now }), newer, "the attempt that expires last, whatever the order it was put in");
+    assert.deepEqual(await latestAttempt({ after: older.expiresAt }), newer);
+    assert.equal(await latestAttempt({ after: newer.expiresAt }), null, "an attempt expiring exactly at `after` is not live");
+  });
+
+  // The same state twice fails with the driver's own duplicate-key error, for the same connection and, because an
+  // attempt's key is its state's hash alone, for another owner's connection too.
+  for (const at of [scope, { owner: { ...owner, subjectId: "user-b" }, integrationId: "calendar" }]) {
+    await assert.rejects(store.withConnection(at, ({ putAttempt }) => putAttempt({ state: "newer", expiresAt: now + 30_000 })), (error) => {
+      assert.equal(error.code, "ER_DUP_ENTRY");
+      return true;
+    });
+  }
+
+  assert.deepEqual(await store.withConnection(scope, ({ consumeAttempt }) => consumeAttempt("older")), older);
+  assert.equal(await store.withConnection(scope, ({ consumeAttempt }) => consumeAttempt("older")), null, "taken once");
+  assert.deepEqual(await store.withConnection(scope, ({ latestAttempt }) => latestAttempt({ after: now })), newer, "the other attempt stays");
+  // A consumed state can be put again.
+  await store.withConnection(scope, ({ putAttempt }) => putAttempt({ state: "older", expiresAt: now + 5_000 }));
+  assert.equal((await store.withConnection(scope, ({ consumeAttempt }) => consumeAttempt("older"))).expiresAt, now + 5_000);
+});
+
+test("pruning removes every connection's attempts that expired by `before`, inclusive, and answers how many", async (context) => {
+  requireTestDatabase(process.env);
+  const store = createKnexConnectionStore({ knex: await ownDatabase(context, "da_conn_prune"), protection });
+  const before = Date.now() + 60_000;
+  const otherScope = { owner: { ...owner, subjectId: "user-b" }, integrationId: "mail" };
+  assert.equal(await store.pruneExpiredAttempts({ before }), 0, "nothing to prune");
+  await store.withConnection(scope, async ({ putAttempt }) => {
+    await putAttempt({ state: "a-expired", expiresAt: before - 1 });
+    await putAttempt({ state: "a-boundary", expiresAt: before });
+    await putAttempt({ state: "a-live", expiresAt: before + 1 });
+  });
+  await store.withConnection(otherScope, ({ putAttempt }) => putAttempt({ state: "b-expired", expiresAt: before - 5_000 }));
+
+  assert.equal(await store.pruneExpiredAttempts({ before }), 3);
+  assert.equal(await store.pruneExpiredAttempts({ before }), 0, "pruning again finds nothing");
+  for (const state of ["a-expired", "a-boundary"]) {
+    assert.equal(await store.withConnection(scope, ({ consumeAttempt }) => consumeAttempt(state)), null, state);
+  }
+  assert.equal(await store.withConnection(otherScope, ({ consumeAttempt }) => consumeAttempt("b-expired")), null);
+  assert.equal((await store.withConnection(scope, ({ consumeAttempt }) => consumeAttempt("a-live"))).state, "a-live");
+
+  // Without `before`, now is the boundary.
+  await store.withConnection(scope, async ({ putAttempt }) => {
+    await putAttempt({ state: "past", expiresAt: Date.now() - 1_000 });
+    await putAttempt({ state: "future", expiresAt: Date.now() + 60_000 });
+  });
+  assert.equal(await store.pruneExpiredAttempts(), 1);
+  assert.equal((await store.withConnection(scope, ({ latestAttempt }) => latestAttempt({ after: 0 }))).state, "future");
+});

package/test/withoutDatabase.test.js

@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { createInstalledRuntime } from "@jskit-ai/kernel/server/platform";
+import { silentLogger } from "@jskit-ai/kernel/server/runtime/logger";
+
+const TABLE_RUNTIME = ["@jskit-ai/database-runtime", "@jskit-ai/resource-runtime"];
+const readManifest = async (url) => JSON.parse(await readFile(url, "utf8"));
+
+/**
+ * An app installed as npm installs it: each package's manifest under node_modules, by name, and nothing else, so no
+ * package of the monorepo is reached by accident.
+ * @param {import("node:test").TestContext} t
+ * @param {object[]} manifests
+ */
+async function installedApp(t, manifests) {
+  const appRoot = await mkdtemp(path.join(tmpdir(), "connectors-core-without-database-"));
+  t.after(() => rm(appRoot, { recursive: true, force: true }));
+  for (const manifest of manifests) {
+    const packageRoot = path.join(appRoot, "node_modules", ...manifest.name.split("/"));
+    await mkdir(packageRoot, { recursive: true });
+    await writeFile(path.join(packageRoot, "package.json"), JSON.stringify(manifest));
+  }
+  const [own] = manifests;
+  await writeFile(path.join(appRoot, "package.json"), JSON.stringify({
+    name: "app-without-database",
+    private: true,
+    dependencies: { [own.name]: own.version }
+  }));
+  return appRoot;
+}
+
+test("an app without a database installs @jskit-ai/connectors-core without the table runtime, composes it and starts", async (t) => {
+  const manifest = await readManifest(new URL("../package.json", import.meta.url));
+  // npm installs a package's dependencies, never its optional peers: the table runtime comes with an app's database.
+  for (const name of TABLE_RUNTIME) {
+    assert.equal(manifest.dependencies?.[name], undefined, `${name} is not a dependency`);
+    assert.equal(manifest.peerDependenciesMeta?.[name]?.optional, true, `${name} is an optional peer`);
+  }
+
+  const started = await createInstalledRuntime({ appRoot: await installedApp(t, [manifest]), logger: silentLogger });
+  assert.ok(started.packageOrder.includes(manifest.name));
+  assert.equal(started.packageOrder.some((name) => TABLE_RUNTIME.includes(name)), false);
+
+  // Installed as a dependency, the table runtime would need a database driver the app does not have.
+  const databaseRuntime = await readManifest(new URL("../../database-runtime/package.json", import.meta.url));
+  await assert.rejects(
+    createInstalledRuntime({ appRoot: await installedApp(t, [manifest, databaseRuntime]), logger: silentLogger }),
+    /requires capability runtime\.database\.driver, but no installed package provides it/u
+  );
+});