@aloma.io/integration-sdk 3.8.67 → 3.8.68

package/README.md

@@ -106,6 +106,66 @@ The SDK includes comprehensive scenario tests that verify:
 
 All tests use real OpenAPI specifications and compare generated output against fixtures to ensure deterministic, high-quality code generation.
 
+### Testing a connector: handshake smoke test
+
+The SDK ships a test harness (`build/testing/`, source in `src/testing/`). It runs your real connector in-process
+against a fake ALOMA endpoint on `127.0.0.1`, performs the real handshake (connect, 401, register, websocket,
+configuration), sends method calls like ALOMA does, and mocks the vendor HTTP API. Any request that is not
+mocked fails the test, and raw connections to non-loopback hosts are blocked, so a test never touches the network.
+No real token or key is needed: the harness generates a throwaway RSA key pair and fake tokens.
+
+A connector repo adds one dev dependency on the SDK (already a dependency) and one file, `test/handshake.smoke.test.mjs`
+(run it with `mocha --exit test/handshake.smoke.test.mjs` after `yarn build`):
+
+```js
+import {describe, it, afterEach} from 'mocha';
+import {expect} from 'chai';
+import {Builder} from '@aloma.io/integration-sdk';
+import {ConnectorHarness, connectorFromRuntimeContext} from '@aloma.io/integration-sdk/build/testing/index.mjs';
+
+describe('handshake smoke test', function () {
+  this.timeout(15000);
+  let harness;
+
+  // stop() also fails the test if the connector made a request you did not mock
+  afterEach(async () => harness && (await harness.stop()));
+
+  it('registers, connects, starts and reports healthy', async () => {
+    // use the same Builder configuration as src/index.mts (config, options, auth)
+    const context = await new Builder().config({fields: {apiKey: {name: 'API Key', type: 'line'}}}).build();
+
+    harness = await ConnectorHarness.start({
+      connector: connectorFromRuntimeContext(context),
+      config: {apiKey: 'fake-api-key-not-real'}, // encrypted for the connector unless the field is `plain`
+    });
+
+    const health = await harness.aloma.waitForPacket('connector.health.check');
+    expect(health.a).to.deep.equal({ok: true, error: null});
+  });
+
+  it('calls a method against a mocked vendor API', async () => {
+    harness = await ConnectorHarness.start({/* same as above */});
+    harness.vendor.get('https://api.vendor.example/things/1', {json: {id: 1}});
+
+    expect(await harness.callOk('getThing', {id: 1})).to.deep.equal({id: 1});
+  });
+});
+```
+
+Useful pieces: `harness.call(method, variables, ctx)` (raw answer, `{error}` on failure), `harness.callOk(...)`,
+`harness.vendor.get/post/put/delete(url | RegExp | fn, {status, json, text, headers} | fn(request))`,
+`harness.vendor.requests` (what the connector sent), `harness.aloma.handle('connector.blob.create', fn)` to answer
+requests the connector makes to ALOMA, `harness.aloma.registration` (what the connector registered).
+`test/harness-connector-smoke.test.mjs` in this repo is a runnable version of the example.
+
+Not covered: the Prometheus metrics server (fixed port 4050), process signal handlers, configuration through
+environment variables and OAuth flows against a real provider. `connectorFromRuntimeContext` repeats the wiring of
+`RuntimeContext.start()`, so keep the two in step.
+
+SDK maintainers: `yarn test:harness` runs the harness tests (CI runs it on Node 18, 20, 22 and 24). `yarn test:mutation`
+applies 30+ deliberate bugs to the harness and the SDK handshake, dispatch and result paths and checks the tests
+catch each one; the result is recorded in `test/MUTATION.md`.
+
 ## 📚 Documentation
 
 - **[OPENAPI_TO_CONNECTOR.md](./OPENAPI_TO_CONNECTOR.md)** - OpenAPI generator details

package/build/testing/fake-aloma.d.mts

@@ -0,0 +1,87 @@
+/// <reference types="node" resolution-mode="require"/>
+import http from 'node:http';
+type Packet = {
+    id?: string;
+    m?: string;
+    c?: string;
+    a?: any;
+    e?: any;
+};
+/**
+ * A fake ALOMA endpoint that speaks the connector protocol, in-process on a loopback port.
+ *
+ * Protocol (taken from src/internal/websocket and src/internal/dispatcher):
+ *  1. POST {url}connect with `Authorization: Connector <token>`. 401 means "register first", 200 + json means connected.
+ *  2. POST {url}register with `Authorization: Connector <registrationToken>` and
+ *     {name, version, id, publicKey, schema:{configSchema, introspect}, icon}; answer 200 {key: <token>}.
+ *  3. The connector opens a websocket at wsUrl (subprotocol "connector", same Authorization header).
+ *  4. Both sides exchange text frames {p: [packet, ...]}; a packet is {id, m: method, c: callback key, a: args}.
+ *  5. ALOMA sends connector.set-config {secrets} (no reply), then connector.query {query, variables} with a
+ *     callback key; the connector answers {c: key, a: result} or {c: key, a: {error}}.
+ *
+ * Anything that does not look like the real protocol is recorded in `protocolErrors`.
+ */
+export declare class FakeAloma {
+    readonly registrationToken: string;
+    readonly sessionToken: string;
+    /** bodies of POST /register */
+    readonly registrations: any[];
+    /** headers of POST /connect */
+    readonly connects: Array<{
+        authorized: boolean;
+        headers: http.IncomingHttpHeaders;
+    }>;
+    /** every packet the connector sent over the websocket, in order */
+    readonly received: Packet[];
+    readonly protocolErrors: string[];
+    private server;
+    private wss;
+    private socket?;
+    private pending;
+    private handlers;
+    private waiters;
+    private port;
+    private id;
+    private version;
+    static start(): Promise<FakeAloma>;
+    /** value for the connector's endpoint setting (env.DEVICE_ENDPOINT) */
+    get url(): string;
+    /** value for the connector's websocket setting (env.WEBSOCKET_ENDPOINT) */
+    get wsUrl(): string;
+    get connected(): boolean;
+    get registration(): any;
+    private listen;
+    private readJson;
+    private onHttp;
+    private onSocket;
+    private onPacket;
+    /** answer connector -> ALOMA requests such as connector.blob.get or connector.task.new */
+    handle(method: string, fn: (args: any) => any | Promise<any>): this;
+    /** resolves when the connector's websocket is open (the handshake is finished) */
+    waitForConnection(timeoutMs?: number): Promise<void>;
+    /** resolves with the first packet the connector sent for `method` (e.g. connector.health.check), now or later */
+    waitForPacket(method: string, timeoutMs?: number): Promise<Packet>;
+    /** send one raw packet to the connector */
+    send(packet: Packet): void;
+    /** send a packet with a callback key and wait for the connector's answer (its `a` field) */
+    request(method: string, args: any, timeoutMs?: number): Promise<any>;
+    /** ask the connector for its schema and method list (connector.introspect) */
+    introspect(): Promise<any>;
+    /**
+     * Send the configuration the way ALOMA does: every field that is not `plain` is a JWE encrypted with the
+     * public key the connector registered, audience = connector id. Resolves after the packet is sent;
+     * the ConnectorHarness waits for the connector's start.
+     */
+    setConfig(values: Record<string, any>): Promise<void>;
+    /**
+     * Call a connector method like ALOMA does (connector.query). Resolves with the connector's raw answer:
+     * an object result is passed through, any other value is wrapped as {[method]: value}, a failure is {error}.
+     */
+    call(method: string | string[], variables?: any, ctx?: {
+        taskId?: string;
+        namespace?: string;
+        sticky?: boolean;
+    }): Promise<any>;
+    close(): Promise<void>;
+}
+export {};

package/build/testing/fake-aloma.mjs

@@ -0,0 +1,248 @@
+import { randomUUID } from 'node:crypto';
+import http from 'node:http';
+import * as jose from 'jose';
+import { WebSocket, WebSocketServer } from 'ws';
+/**
+ * A fake ALOMA endpoint that speaks the connector protocol, in-process on a loopback port.
+ *
+ * Protocol (taken from src/internal/websocket and src/internal/dispatcher):
+ *  1. POST {url}connect with `Authorization: Connector <token>`. 401 means "register first", 200 + json means connected.
+ *  2. POST {url}register with `Authorization: Connector <registrationToken>` and
+ *     {name, version, id, publicKey, schema:{configSchema, introspect}, icon}; answer 200 {key: <token>}.
+ *  3. The connector opens a websocket at wsUrl (subprotocol "connector", same Authorization header).
+ *  4. Both sides exchange text frames {p: [packet, ...]}; a packet is {id, m: method, c: callback key, a: args}.
+ *  5. ALOMA sends connector.set-config {secrets} (no reply), then connector.query {query, variables} with a
+ *     callback key; the connector answers {c: key, a: result} or {c: key, a: {error}}.
+ *
+ * Anything that does not look like the real protocol is recorded in `protocolErrors`.
+ */
+export class FakeAloma {
+    registrationToken = `fake-registration-${randomUUID()}`;
+    sessionToken = `fake-session-${randomUUID()}`;
+    /** bodies of POST /register */
+    registrations = [];
+    /** headers of POST /connect */
+    connects = [];
+    /** every packet the connector sent over the websocket, in order */
+    received = [];
+    protocolErrors = [];
+    server;
+    wss;
+    socket;
+    pending = new Map();
+    handlers = new Map();
+    waiters = [];
+    port = 0;
+    id = '';
+    version = '';
+    static async start() {
+        const fake = new FakeAloma();
+        await fake.listen();
+        return fake;
+    }
+    /** value for the connector's endpoint setting (env.DEVICE_ENDPOINT) */
+    get url() {
+        return `http://127.0.0.1:${this.port}/`;
+    }
+    /** value for the connector's websocket setting (env.WEBSOCKET_ENDPOINT) */
+    get wsUrl() {
+        return `ws://127.0.0.1:${this.port}/transport/`;
+    }
+    get connected() {
+        return this.socket?.readyState === WebSocket.OPEN;
+    }
+    get registration() {
+        return this.registrations[this.registrations.length - 1];
+    }
+    async listen() {
+        this.server = http.createServer((req, res) => {
+            this.onHttp(req, res).catch((e) => {
+                this.protocolErrors.push(`http handler failed: ${e}`);
+                res.writeHead(500).end();
+            });
+        });
+        this.wss = new WebSocketServer({
+            noServer: true,
+            handleProtocols: (protocols) => (protocols.has('connector') ? 'connector' : false),
+        });
+        this.server.on('upgrade', (req, socket, head) => {
+            const problems = [];
+            if (req.headers.authorization !== `Connector ${this.sessionToken}`)
+                problems.push('bad or missing Authorization on websocket');
+            if (!String(req.headers['sec-websocket-protocol'] || '').split(/,\s*/).includes('connector')) {
+                problems.push('websocket subprotocol "connector" not requested');
+            }
+            if (problems.length) {
+                this.protocolErrors.push(...problems);
+                socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n');
+                socket.destroy();
+                return;
+            }
+            this.wss.handleUpgrade(req, socket, head, (ws) => this.onSocket(ws));
+        });
+        await new Promise((resolve) => this.server.listen(0, '127.0.0.1', () => resolve()));
+        this.port = this.server.address().port;
+    }
+    async readJson(req) {
+        let text = '';
+        for await (const chunk of req)
+            text += chunk;
+        return text ? JSON.parse(text) : {};
+    }
+    async onHttp(req, res) {
+        const send = (status, body) => {
+            res.writeHead(status, { 'Content-Type': 'application/json' });
+            res.end(body === undefined ? '' : JSON.stringify(body));
+        };
+        const body = await this.readJson(req);
+        const auth = req.headers.authorization;
+        if (req.method === 'POST' && req.url === '/connect') {
+            const authorized = auth === `Connector ${this.sessionToken}`;
+            this.connects.push({ authorized, headers: req.headers });
+            return authorized ? send(200, {}) : send(401);
+        }
+        if (req.method === 'POST' && req.url === '/register') {
+            if (auth !== `Connector ${this.registrationToken}`) {
+                this.protocolErrors.push('register called with a wrong registration token');
+                return send(401);
+            }
+            const missing = ['name', 'version', 'id', 'publicKey', 'schema'].filter((key) => body[key] == null);
+            if (missing.length)
+                this.protocolErrors.push(`register body is missing: ${missing.join(', ')}`);
+            this.id = body.id;
+            this.version = body.version;
+            if (req.headers['user-agent'] !== `${body.id}/${body.version}`) {
+                this.protocolErrors.push(`register User-Agent should be id/version, got ${req.headers['user-agent']}`);
+            }
+            this.registrations.push(body);
+            return send(200, { key: this.sessionToken });
+        }
+        if (req.method === 'POST' && req.url === '/disconnect')
+            return send(200, {});
+        this.protocolErrors.push(`unexpected request ${req.method} ${req.url}`);
+        send(404);
+    }
+    onSocket(ws) {
+        this.socket = ws;
+        ws.on('message', (raw) => {
+            const frame = JSON.parse(raw.toString());
+            const packets = frame.p;
+            if (!Array.isArray(packets)) {
+                this.protocolErrors.push('frame without a "p" array');
+                return;
+            }
+            packets.forEach((packet) => this.onPacket(packet));
+        });
+        this.waiters.splice(0).forEach((fn) => fn());
+    }
+    onPacket(packet) {
+        this.received.push(packet);
+        // an answer to something ALOMA sent
+        if (packet.c && !packet.m && this.pending.has(packet.c)) {
+            const done = this.pending.get(packet.c);
+            this.pending.delete(packet.c);
+            done(packet.a);
+            return;
+        }
+        // the connector asks ALOMA for something (blob, task, ...) and expects an answer on its callback key
+        if (packet.m && this.handlers.has(packet.m)) {
+            Promise.resolve(this.handlers.get(packet.m)(packet.a)).then((answer) => packet.c && this.send({ c: packet.c, a: answer }), (e) => packet.c && this.send({ c: packet.c, a: { error: String(e) } }));
+        }
+    }
+    /** answer connector -> ALOMA requests such as connector.blob.get or connector.task.new */
+    handle(method, fn) {
+        this.handlers.set(method, fn);
+        return this;
+    }
+    /** resolves when the connector's websocket is open (the handshake is finished) */
+    async waitForConnection(timeoutMs = 5000) {
+        if (this.connected)
+            return;
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new Error(`connector did not connect within ${timeoutMs}ms. registrations=${this.registrations.length} ` +
+                    `connects=${this.connects.length} protocolErrors=${JSON.stringify(this.protocolErrors)}`));
+            }, timeoutMs);
+            this.waiters.push(() => {
+                clearTimeout(timer);
+                resolve();
+            });
+        });
+    }
+    /** resolves with the first packet the connector sent for `method` (e.g. connector.health.check), now or later */
+    async waitForPacket(method, timeoutMs = 5000) {
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            const found = this.received.find((packet) => packet.m === method);
+            if (found)
+                return found;
+            if (Date.now() > deadline)
+                throw new Error(`connector did not send ${method} within ${timeoutMs}ms`);
+            await new Promise((resolve) => setTimeout(resolve, 10));
+        }
+    }
+    /** send one raw packet to the connector */
+    send(packet) {
+        if (!this.connected)
+            throw new Error('connector is not connected');
+        this.socket.send(JSON.stringify({ p: [{ id: randomUUID(), ...packet }] }));
+    }
+    /** send a packet with a callback key and wait for the connector's answer (its `a` field) */
+    request(method, args, timeoutMs = 5000) {
+        const key = `_req-${randomUUID()}`;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(key);
+                reject(new Error(`no answer to ${method} within ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pending.set(key, (answer) => {
+                clearTimeout(timer);
+                resolve(answer);
+            });
+            this.send({ m: method, c: key, a: args });
+        });
+    }
+    /** ask the connector for its schema and method list (connector.introspect) */
+    introspect() {
+        return this.request('connector.introspect', {});
+    }
+    /**
+     * Send the configuration the way ALOMA does: every field that is not `plain` is a JWE encrypted with the
+     * public key the connector registered, audience = connector id. Resolves after the packet is sent;
+     * the ConnectorHarness waits for the connector's start.
+     */
+    async setConfig(values) {
+        if (!this.registration)
+            throw new Error('connector has not registered yet');
+        const fields = this.registration.schema?.configSchema?.fields || {};
+        const publicKey = await jose.importSPKI(Buffer.from(this.registration.publicKey, 'base64').toString(), 'RSA-OAEP-256');
+        const secrets = {};
+        for (const [key, value] of Object.entries(values)) {
+            if (fields[key]?.plain || key === 'endpointUrl') {
+                secrets[key] = value;
+                continue;
+            }
+            secrets[key] = await new jose.EncryptJWT({ _data: value })
+                .setProtectedHeader({ alg: 'RSA-OAEP-256', enc: 'A256GCM' })
+                .setIssuedAt()
+                .setIssuer('home.aloma.io')
+                .setAudience(this.id)
+                .encrypt(publicKey);
+        }
+        this.send({ m: 'connector.set-config', a: { secrets } });
+    }
+    /**
+     * Call a connector method like ALOMA does (connector.query). Resolves with the connector's raw answer:
+     * an object result is passed through, any other value is wrapped as {[method]: value}, a failure is {error}.
+     */
+    call(method, variables, ctx = {}) {
+        return this.request('connector.query', { query: method, variables, ...ctx });
+    }
+    async close() {
+        this.pending.clear();
+        this.wss.clients.forEach((client) => client.terminate());
+        this.wss.close();
+        this.server.closeAllConnections?.();
+        await new Promise((resolve) => this.server.close(() => resolve()));
+    }
+}

package/build/testing/harness.d.mts

@@ -0,0 +1,51 @@
+import type { Connector } from '../internal/connector/index.mjs';
+import { FakeAloma } from './fake-aloma.mjs';
+import { VendorMock } from './vendor-mock.mjs';
+export type HarnessOptions = {
+    /**
+     * The connector under test, already configured:
+     * `const c = new Connector({id, version, name}); c.configure().types(...).resolvers(...).main(...)`
+     */
+    connector: Connector;
+    /** vendor mock; a fresh one is created when omitted */
+    vendor?: VendorMock;
+    /**
+     * configuration values ALOMA sends after the handshake (encrypted unless the field is `plain`).
+     * `null` skips sending any configuration (the connector then never starts its main()).
+     */
+    config?: Record<string, any> | null;
+    /** how long to wait for each step, ms */
+    timeoutMs?: number;
+};
+/**
+ * Runs a real connector against a fake ALOMA, in-process.
+ *
+ * It wires the same SDK parts as Connector.run() and makeServer(): Config, WebsocketConnector (connection,
+ * registration, transport), onConnect (config decryption, main()), onMessage (dispatch and reply).
+ * Left out on purpose: the Prometheus metrics server (fixed port 4050), process signal handlers and
+ * env-var configuration, which are global side effects that cannot run once per test.
+ */
+export declare class ConnectorHarness {
+    readonly aloma: FakeAloma;
+    readonly vendor: VendorMock;
+    private readonly server;
+    private readonly started;
+    private constructor();
+    static start(options: HarnessOptions): Promise<ConnectorHarness>;
+    private static shutdown;
+    /** call a connector method and return the raw answer (`{error}` when it failed) */
+    call(method: string | string[], variables?: any, ctx?: {
+        taskId?: string;
+        namespace?: string;
+        sticky?: boolean;
+    }): Promise<any>;
+    /** call a connector method; throws when the connector answered with an error */
+    callOk(method: string | string[], variables?: any): Promise<any>;
+    /**
+     * Shut down the connector and the fake endpoint, restore fetch and the network guard.
+     * Then fails if the connector made any request that was not mocked or the fake endpoint saw a protocol error.
+     */
+    stop({ verify }?: {
+        verify?: boolean;
+    }): Promise<void>;
+}

package/build/testing/harness.mjs

@@ -0,0 +1,139 @@
+import { Config } from '../internal/websocket/config.mjs';
+import { WebsocketConnector } from '../internal/websocket/index.mjs';
+import { onConnect } from '../internal/connector/server/on-connect/index.mjs';
+import { onMessage } from '../internal/connector/server/on-message.mjs';
+import { FakeAloma } from './fake-aloma.mjs';
+import { testKeyPair } from './keys.mjs';
+import { VendorMock } from './vendor-mock.mjs';
+/**
+ * Runs a real connector against a fake ALOMA, in-process.
+ *
+ * It wires the same SDK parts as Connector.run() and makeServer(): Config, WebsocketConnector (connection,
+ * registration, transport), onConnect (config decryption, main()), onMessage (dispatch and reply).
+ * Left out on purpose: the Prometheus metrics server (fixed port 4050), process signal handlers and
+ * env-var configuration, which are global side effects that cannot run once per test.
+ */
+export class ConnectorHarness {
+    aloma;
+    vendor;
+    server;
+    started;
+    constructor(aloma, vendor, server, started) {
+        this.aloma = aloma;
+        this.vendor = vendor;
+        this.server = server;
+        this.started = started;
+    }
+    static async start(options) {
+        const { connector, timeoutMs = 5000 } = options;
+        const dispatcher = connector.dispatcher;
+        if (!dispatcher)
+            throw new Error('call connector.configure() before starting the harness');
+        const vendor = options.vendor || new VendorMock();
+        const aloma = await FakeAloma.start();
+        vendor.allowPassthrough((url) => url.origin === new URL(aloma.url).origin);
+        vendor.install();
+        // main() is what a connector runs once ALOMA has sent its configuration; observe it
+        let mainDone;
+        let mainFailed;
+        const started = new Promise((resolve, reject) => {
+            mainDone = resolve;
+            mainFailed = reject;
+        });
+        started.catch(() => { });
+        const originalMain = dispatcher._main;
+        dispatcher.main(async (arg) => {
+            try {
+                await originalMain?.(arg);
+                mainDone();
+            }
+            catch (e) {
+                mainFailed(e);
+                throw e;
+            }
+        });
+        let server;
+        try {
+            const { processPacket, start, introspect, configSchema } = dispatcher.build();
+            const keys = await testKeyPair();
+            const config = new Config({
+                id: connector.id,
+                version: connector.version,
+                name: connector.name,
+                registrationToken: aloma.registrationToken,
+                endpoint: aloma.url,
+                wsEndpoint: aloma.wsUrl,
+                privateKey: keys.privateKey,
+                publicKey: keys.publicKey,
+                introspect,
+                configSchema,
+                icon: connector.icon,
+            });
+            server = new WebsocketConnector({
+                config,
+                onConnect: onConnect({ config, configSchema, dispatcher, start }),
+                onMessage: onMessage(processPacket),
+            });
+            const harness = new ConnectorHarness(aloma, vendor, server, options.config === null ? null : started);
+            await server.start();
+            await aloma.waitForConnection(timeoutMs);
+            if (options.config !== null) {
+                await aloma.setConfig(options.config || {});
+                await withTimeout(started, timeoutMs, 'connector main() did not finish after the configuration was sent');
+            }
+            return harness;
+        }
+        catch (e) {
+            await ConnectorHarness.shutdown(server, vendor, aloma);
+            throw e;
+        }
+    }
+    static async shutdown(server, vendor, aloma) {
+        try {
+            if (server) {
+                const anyServer = server;
+                await anyServer.leaving();
+                await anyServer.close();
+                // the SDK leaves a 45s ping watchdog timer behind; clear it so a test run can exit
+                clearTimeout(anyServer.transport?.ws?.pingTimeout);
+            }
+        }
+        finally {
+            vendor.uninstall();
+            await aloma.close();
+        }
+    }
+    /** call a connector method and return the raw answer (`{error}` when it failed) */
+    call(method, variables, ctx) {
+        return this.aloma.call(method, variables, ctx);
+    }
+    /** call a connector method; throws when the connector answered with an error */
+    async callOk(method, variables) {
+        const answer = await this.call(method, variables);
+        if (answer?.error)
+            throw new Error(`${method} failed: ${answer.error}`);
+        return answer;
+    }
+    /**
+     * Shut down the connector and the fake endpoint, restore fetch and the network guard.
+     * Then fails if the connector made any request that was not mocked or the fake endpoint saw a protocol error.
+     */
+    async stop({ verify = true } = {}) {
+        await ConnectorHarness.shutdown(this.server, this.vendor, this.aloma);
+        if (verify) {
+            this.vendor.verify();
+            if (this.aloma.protocolErrors.length) {
+                throw new Error(`protocol errors seen by the fake ALOMA: ${JSON.stringify(this.aloma.protocolErrors)}`);
+            }
+        }
+    }
+}
+const withTimeout = (promise, ms, message) => {
+    let timer;
+    return Promise.race([
+        promise,
+        new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(message)), ms);
+        }),
+    ]).finally(() => clearTimeout(timer));
+};

package/build/testing/index.d.mts

@@ -0,0 +1,15 @@
+/**
+ * Test harness for connectors built on the ALOMA integration SDK.
+ *
+ *   import {ConnectorHarness, VendorMock} from '@aloma.io/integration-sdk/build/testing/index.mjs';
+ *
+ * Test tooling only: nothing in the SDK runtime imports this folder.
+ */
+export { ConnectorHarness } from './harness.mjs';
+export type { HarnessOptions } from './harness.mjs';
+export { FakeAloma } from './fake-aloma.mjs';
+export { VendorMock } from './vendor-mock.mjs';
+export type { VendorRequest, VendorResponse, VendorResponder, UrlMatcher } from './vendor-mock.mjs';
+export { installNetworkGuard, uninstallNetworkGuard } from './network-guard.mjs';
+export { testKeyPair } from './keys.mjs';
+export { connectorFromRuntimeContext } from './runtime-connector.mjs';

package/build/testing/index.mjs

@@ -0,0 +1,13 @@
+/**
+ * Test harness for connectors built on the ALOMA integration SDK.
+ *
+ *   import {ConnectorHarness, VendorMock} from '@aloma.io/integration-sdk/build/testing/index.mjs';
+ *
+ * Test tooling only: nothing in the SDK runtime imports this folder.
+ */
+export { ConnectorHarness } from './harness.mjs';
+export { FakeAloma } from './fake-aloma.mjs';
+export { VendorMock } from './vendor-mock.mjs';
+export { installNetworkGuard, uninstallNetworkGuard } from './network-guard.mjs';
+export { testKeyPair } from './keys.mjs';
+export { connectorFromRuntimeContext } from './runtime-connector.mjs';

package/build/testing/keys.d.mts

@@ -0,0 +1,9 @@
+/**
+ * One throwaway RSA key pair per process, generated at test time.
+ * Never committed, never a real key. Same encoding the connector expects in
+ * env.PRIVATE_KEY / env.PUBLIC_KEY (base64 of the PEM).
+ */
+export declare const testKeyPair: () => Promise<{
+    privateKey: string;
+    publicKey: string;
+}>;

package/build/testing/keys.mjs

@@ -0,0 +1,15 @@
+import JWE from '../internal/util/jwe/index.mjs';
+let pair;
+/**
+ * One throwaway RSA key pair per process, generated at test time.
+ * Never committed, never a real key. Same encoding the connector expects in
+ * env.PRIVATE_KEY / env.PUBLIC_KEY (base64 of the PEM).
+ */
+export const testKeyPair = () => {
+    pair ||= (async () => {
+        const jwe = new JWE({ algorithm: 'RSA-OAEP-256' });
+        await jwe.newPair();
+        return { privateKey: await jwe.exportPrivateAsBase64(), publicKey: await jwe.exportPublicAsBase64() };
+    })();
+    return pair;
+};

package/build/testing/network-guard.d.mts

@@ -0,0 +1,3 @@
+export declare const blocked: string[];
+export declare const installNetworkGuard: () => void;
+export declare const uninstallNetworkGuard: () => void;