@tapicker/bridge 1.0.0

package/dist/server.js

@@ -0,0 +1,486 @@
+import { createServer as createHttpServer, } from 'node:http';
+import { createServer as createHttpsServer } from 'node:https';
+import { readFileSync } from 'node:fs';
+import { randomInt, randomUUID, timingSafeEqual } from 'node:crypto';
+import { URL } from 'node:url';
+import { join, resolve } from 'node:path';
+import { WebSocketServer } from 'ws';
+import { createMcpHandler } from '@modelcontextprotocol/server';
+import { localhostHostValidation, toNodeHandler } from '@modelcontextprotocol/node';
+import { DEFAULT_HOST, DEFAULT_MCP_PATH, DEFAULT_PORT, DEFAULT_PORT_MAX, DEFAULT_WS_PATH, DEFAULT_WORKFLOW_WATCH_WS_PATH, PROTOCOL_VERSION, VERSION, } from './constants.js';
+import { BridgeService } from './bridge/bridge-service.js';
+import { PairingStateFile } from './bridge/pairing-state.js';
+import { getCommandCapabilities, dispatchCommand } from './commands.js';
+import { BridgeError, safeError, safeSuccess, toBridgeError } from './errors.js';
+import { createBridgeMcpApi, createTapickerMcpServer } from './mcp.js';
+import { WorkflowWatchRequestSchema, createEnvelope, parseEnvelope } from './protocol/schema.js';
+const DEFAULT_CORS_ORIGINS = ['*'];
+const CORS_ALLOWED_METHODS = 'GET, POST, DELETE, OPTIONS';
+const CORS_ALLOWED_HEADERS = 'Accept, Authorization, Content-Type, Last-Event-ID, MCP-Protocol-Version, Mcp-Session-Id';
+const CORS_EXPOSED_HEADERS = 'MCP-Protocol-Version, Mcp-Session-Id';
+export class BridgeServer {
+    bridgeId = randomUUID();
+    bridge;
+    host;
+    requestedPort;
+    portMax;
+    token;
+    corsOrigins;
+    tls;
+    mcpHandler;
+    mcpNodeHandler;
+    validateLocalMcpHost = localhostHostValidation();
+    server;
+    webSocketServer;
+    port;
+    workflowSubscriptions = new Map();
+    constructor(options = {}) {
+        this.host = options.host ?? DEFAULT_HOST;
+        this.requestedPort = options.port;
+        this.portMax = options.portMax ?? DEFAULT_PORT_MAX;
+        this.token = options.token;
+        this.corsOrigins = normalizeCorsOrigins(options.corsOrigins ?? DEFAULT_CORS_ORIGINS);
+        this.tls = options.tls;
+        const pairingState = options.dataDir
+            ? new PairingStateFile(join(resolve(options.dataDir), 'paired-clients.json'))
+            : undefined;
+        this.bridge = new BridgeService({
+            pairingCode: options.pairingCode ?? String(randomInt(0, 10_000)).padStart(4, '0'),
+            capabilities: [
+                'workflow.start',
+                'workflow.pause',
+                'workflow.resume',
+                'workflow.stop',
+                'workflow.status',
+                'workflow.status.get',
+                'data.get',
+                'data.delete',
+            ],
+            pairingState,
+        });
+        this.mcpHandler = createMcpHandler(() => createTapickerMcpServer(createBridgeMcpApi(this.bridge)));
+        this.mcpNodeHandler = toNodeHandler(this.mcpHandler, {
+            onerror: (error) => console.error('Tapicker Bridge MCP request failed:', error),
+        });
+        this.bridge.on('workflow.status', (event) => this.publishWorkflowStatus(event));
+    }
+    getPairingCode() {
+        return this.bridge.getPairingCode();
+    }
+    refreshPairingCode() {
+        return this.bridge.refreshPairingCode();
+    }
+    async start() {
+        if (this.server && this.port !== undefined) {
+            return this.getAddress();
+        }
+        await this.bridge.initialize();
+        const ports = this.getPorts();
+        let lastError;
+        for (const port of ports) {
+            const runtime = this.createRuntime();
+            try {
+                const actualPort = await listen(runtime.server, this.host, port);
+                this.server = runtime.server;
+                this.webSocketServer = runtime.webSocketServer;
+                this.port = actualPort;
+                return this.getAddress();
+            }
+            catch (error) {
+                await closeServer(runtime.server);
+                runtime.webSocketServer.close();
+                if (isAddressInUseError(error) && this.requestedPort === undefined) {
+                    lastError = error;
+                    continue;
+                }
+                throw error;
+            }
+        }
+        throw toBridgeError(lastError, 'PortUnavailable', 503);
+    }
+    async close() {
+        this.bridge.close();
+        this.workflowSubscriptions.clear();
+        await this.mcpHandler.close();
+        this.webSocketServer?.clients.forEach((client) => client.terminate());
+        await closeWebSocketServer(this.webSocketServer);
+        await closeServer(this.server);
+        this.server = undefined;
+        this.webSocketServer = undefined;
+        this.port = undefined;
+    }
+    getAddress() {
+        if (!this.port) {
+            throw new BridgeError('BridgeNotStarted', 'Bridge server has not started', { status: 500 });
+        }
+        const secure = Boolean(this.tls);
+        const protocol = secure ? 'https' : 'http';
+        const webSocketProtocol = secure ? 'wss' : 'ws';
+        const displayHost = this.host === '0.0.0.0' || this.host === '::' ? '127.0.0.1' : this.host;
+        return {
+            host: this.host,
+            port: this.port,
+            httpUrl: `${protocol}://${displayHost}:${this.port}`,
+            wsUrl: `${webSocketProtocol}://${displayHost}:${this.port}${DEFAULT_WS_PATH}`,
+            workflowWatchWsUrl: `${webSocketProtocol}://${displayHost}:${this.port}${DEFAULT_WORKFLOW_WATCH_WS_PATH}`,
+            mcpUrl: `${protocol}://${displayHost}:${this.port}${DEFAULT_MCP_PATH}`,
+        };
+    }
+    getPorts() {
+        if (this.requestedPort !== undefined) {
+            return [this.requestedPort];
+        }
+        return Array.from({ length: this.portMax - DEFAULT_PORT + 1 }, (_, index) => DEFAULT_PORT + index);
+    }
+    createRuntime() {
+        const requestHandler = (request, response) => {
+            void this.handleRequest(request, response);
+        };
+        const server = this.tls
+            ? createHttpsServer({
+                key: readFileSync(this.tls.key),
+                cert: readFileSync(this.tls.cert),
+            }, requestHandler)
+            : createHttpServer(requestHandler);
+        const webSocketServer = new WebSocketServer({ noServer: true });
+        server.on('upgrade', (request, socket, head) => {
+            const requestUrl = new URL(request.url || '/', this.getOrigin(request));
+            if (requestUrl.pathname === DEFAULT_WORKFLOW_WATCH_WS_PATH) {
+                try {
+                    this.assertAuthorized(request);
+                }
+                catch (error) {
+                    rejectUpgrade(socket, toBridgeError(error));
+                    return;
+                }
+                webSocketServer.handleUpgrade(request, socket, head, (client) => this.attachWorkflowWatcher(client));
+                return;
+            }
+            if (requestUrl.pathname !== DEFAULT_WS_PATH) {
+                socket.destroy();
+                return;
+            }
+            webSocketServer.handleUpgrade(request, socket, head, (client) => {
+                this.bridge.attachExtension(client, request.socket.remoteAddress);
+            });
+        });
+        return { server, webSocketServer };
+    }
+    async handleRequest(request, response) {
+        try {
+            const requestUrl = new URL(request.url || '/', this.getOrigin(request));
+            const method = request.method || 'GET';
+            if (!this.applyCors(request, response)) {
+                this.sendJson(response, 403, safeError(new BridgeError('CorsOriginNotAllowed', 'Cross-origin requests from this Origin are not allowed', {
+                    status: 403,
+                })));
+                return;
+            }
+            if (method === 'OPTIONS') {
+                response.statusCode = 204;
+                response.end();
+                return;
+            }
+            if (requestUrl.pathname === DEFAULT_MCP_PATH) {
+                if (isLoopbackHost(this.host) && !this.validateLocalMcpHost(request, response)) {
+                    return;
+                }
+                this.assertAuthorized(request);
+                await this.mcpNodeHandler(request, response);
+                return;
+            }
+            if (method === 'GET' && requestUrl.pathname === '/v1/health') {
+                this.sendJson(response, 200, {
+                    ok: true,
+                    service: 'tapicker-bridge',
+                    version: VERSION,
+                    protocolVersion: PROTOCOL_VERSION,
+                    bridgeId: this.bridgeId,
+                });
+                return;
+            }
+            if (method === 'GET' && requestUrl.pathname === '/v1/discovery') {
+                this.sendJson(response, 200, {
+                    service: 'tapicker-bridge',
+                    version: VERSION,
+                    protocolVersion: PROTOCOL_VERSION,
+                    bridgeId: this.bridgeId,
+                    wsPath: DEFAULT_WS_PATH,
+                    workflowWatchPath: DEFAULT_WORKFLOW_WATCH_WS_PATH,
+                    requiresAuthentication: Boolean(this.token),
+                });
+                return;
+            }
+            if (method === 'GET' && requestUrl.pathname === '/v1/capabilities') {
+                this.sendJson(response, 200, {
+                    protocolVersion: PROTOCOL_VERSION,
+                    commands: getCommandCapabilities(),
+                });
+                return;
+            }
+            if (method === 'GET' && requestUrl.pathname === '/v1/extensions') {
+                this.assertAuthorized(request);
+                this.sendJson(response, 200, {
+                    extensions: this.bridge.getExtensionStatuses(),
+                });
+                return;
+            }
+            if (requestUrl.pathname === DEFAULT_WORKFLOW_WATCH_WS_PATH) {
+                this.assertAuthorized(request);
+                this.sendJson(response, 405, safeError(new BridgeError('WebSocketRequired', 'workflow.watch requires a WebSocket connection', { status: 405 })));
+                return;
+            }
+            if (method === 'POST' && requestUrl.pathname.startsWith('/v1/commands/')) {
+                this.assertAuthorized(request);
+                const commandName = decodeURIComponent(requestUrl.pathname.slice('/v1/commands/'.length));
+                const body = await readJson(request);
+                const data = await dispatchCommand(commandName, body, { bridge: this.bridge });
+                this.sendJson(response, 200, safeSuccess(data));
+                return;
+            }
+            this.sendJson(response, 404, safeError(new BridgeError('NotFound', 'Route not found', { status: 404 })));
+        }
+        catch (error) {
+            const bridgeError = toBridgeError(error);
+            this.sendJson(response, bridgeError.status, safeError(bridgeError));
+        }
+    }
+    assertAuthorized(request) {
+        if (!this.token) {
+            return;
+        }
+        const authorization = request.headers.authorization;
+        const provided = authorization?.startsWith('Bearer ') ? authorization.slice('Bearer '.length) : undefined;
+        if (!provided || !constantTimeEqual(provided, this.token)) {
+            throw new BridgeError('Unauthorized', 'Bridge authentication is required', { status: 401 });
+        }
+    }
+    attachWorkflowWatcher(socket) {
+        const remove = () => this.workflowSubscriptions.delete(socket);
+        socket.on('close', remove);
+        socket.on('error', remove);
+        socket.on('message', (raw) => {
+            const parsedEnvelope = parseEnvelope(raw);
+            if (!parsedEnvelope.success) {
+                socket.close(1007, 'Invalid Workflow watch message');
+                return;
+            }
+            const request = parsedEnvelope.data;
+            if (request.type !== 'workflow.watch') {
+                this.sendWorkflowWatchResult(socket, request.id, safeError(new BridgeError('UnsupportedMessage', 'Only workflow.watch is supported on this socket', {
+                    status: 400,
+                })));
+                return;
+            }
+            const parsedRequest = WorkflowWatchRequestSchema.safeParse(request.data);
+            if (!parsedRequest.success) {
+                this.sendWorkflowWatchResult(socket, request.id, safeError(new BridgeError('InvalidArguments', 'Invalid Workflow watch arguments', {
+                    status: 400,
+                    details: parsedRequest.error.issues,
+                })));
+                return;
+            }
+            if (this.workflowSubscriptions.has(socket)) {
+                this.sendWorkflowWatchResult(socket, request.id, safeError(new BridgeError('WorkflowWatchAlreadyStarted', 'This socket is already watching a Workflow', {
+                    status: 409,
+                })));
+                return;
+            }
+            const watchRequest = parsedRequest.data;
+            try {
+                const clientId = this.bridge.resolveCommandClientId('workflow.status', watchRequest.clientId);
+                const subscription = { clientId, workflowId: watchRequest.input.workflowId };
+                this.workflowSubscriptions.set(socket, subscription);
+                this.sendWorkflowWatchResult(socket, request.id, safeSuccess(subscription));
+            }
+            catch (error) {
+                this.sendWorkflowWatchResult(socket, request.id, safeError(error));
+            }
+        });
+    }
+    sendWorkflowWatchResult(socket, id, data) {
+        if (socket.readyState === socket.OPEN) {
+            try {
+                socket.send(JSON.stringify(createEnvelope('workflow.watch:res', data, { id, callback: false })));
+            }
+            catch {
+                this.workflowSubscriptions.delete(socket);
+            }
+        }
+    }
+    publishWorkflowStatus(event) {
+        const envelope = JSON.stringify(createEnvelope('workflow.status', event, { callback: false }));
+        for (const [socket, subscription] of this.workflowSubscriptions) {
+            if (socket.readyState === socket.OPEN && subscriptionKey(subscription) === subscriptionKey(event)) {
+                try {
+                    socket.send(envelope);
+                }
+                catch {
+                    this.workflowSubscriptions.delete(socket);
+                }
+            }
+        }
+    }
+    getOrigin(request) {
+        const host = request.headers.host || `${this.host}:${this.port || DEFAULT_PORT}`;
+        return `${this.tls ? 'https' : 'http'}://${host}`;
+    }
+    applyCors(request, response) {
+        const origin = request.headers.origin;
+        if (!origin)
+            return true;
+        const allowsAnyOrigin = this.corsOrigins.includes('*');
+        let allowedOrigin;
+        if (allowsAnyOrigin) {
+            allowedOrigin = '*';
+        }
+        else {
+            try {
+                allowedOrigin = normalizeCorsOrigin(origin);
+            }
+            catch {
+                return false;
+            }
+            if (!this.corsOrigins.includes(allowedOrigin))
+                return false;
+            appendVaryOrigin(response);
+        }
+        response.setHeader('Access-Control-Allow-Origin', allowedOrigin);
+        response.setHeader('Access-Control-Allow-Methods', CORS_ALLOWED_METHODS);
+        response.setHeader('Access-Control-Allow-Headers', CORS_ALLOWED_HEADERS);
+        response.setHeader('Access-Control-Expose-Headers', CORS_EXPOSED_HEADERS);
+        response.setHeader('Access-Control-Max-Age', '600');
+        return true;
+    }
+    sendJson(response, status, body) {
+        const payload = JSON.stringify(body);
+        response.statusCode = status;
+        response.setHeader('Content-Type', 'application/json; charset=utf-8');
+        response.setHeader('Content-Length', Buffer.byteLength(payload));
+        response.end(payload);
+    }
+}
+function normalizeCorsOrigins(origins) {
+    const normalized = [...new Set(origins.map(normalizeCorsOrigin))];
+    return normalized.includes('*') ? ['*'] : normalized;
+}
+function normalizeCorsOrigin(origin) {
+    const value = origin.trim();
+    if (value === '*')
+        return value;
+    try {
+        const url = new URL(value);
+        if (!url.protocol || !url.host || url.username || url.password || url.pathname !== '/' || url.search || url.hash) {
+            throw new Error('Expected an origin without a path, query, or fragment');
+        }
+        return url.origin === 'null' ? `${url.protocol}//${url.host}` : url.origin;
+    }
+    catch (error) {
+        throw new BridgeError('InvalidCorsOrigin', `Invalid CORS origin: ${origin}`, {
+            status: 400,
+            cause: error,
+        });
+    }
+}
+function appendVaryOrigin(response) {
+    const existing = response.getHeader('Vary');
+    const values = (Array.isArray(existing) ? existing.join(',') : existing?.toString() || '')
+        .split(',')
+        .map((value) => value.trim())
+        .filter(Boolean);
+    if (!values.some((value) => value.toLowerCase() === 'origin')) {
+        values.push('Origin');
+    }
+    response.setHeader('Vary', values.join(', '));
+}
+function subscriptionKey(subscription) {
+    return `${subscription.clientId}\u0000${subscription.workflowId}`;
+}
+function rejectUpgrade(socket, error) {
+    const body = JSON.stringify(safeError(error));
+    const statusMessage = error.status === 401 ? 'Unauthorized' : 'Forbidden';
+    socket.write(`HTTP/1.1 ${error.status} ${statusMessage}\r\nConnection: close\r\nContent-Type: application/json\r\nContent-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`);
+    socket.destroy();
+}
+function listen(server, host, port) {
+    return new Promise((resolve, reject) => {
+        const onError = (error) => {
+            server.off('listening', onListening);
+            reject(error);
+        };
+        const onListening = () => {
+            server.off('error', onError);
+            const address = server.address();
+            if (!address || typeof address === 'string') {
+                reject(new BridgeError('InvalidServerAddress', 'Cannot read the Bridge server address', { status: 500 }));
+                return;
+            }
+            resolve(address.port);
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(port, host);
+    });
+}
+function closeServer(server) {
+    if (!server || !server.listening) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        server.close(() => resolve());
+    });
+}
+function closeWebSocketServer(server) {
+    if (!server) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        server.close(() => resolve());
+    });
+}
+function isAddressInUseError(error) {
+    return Boolean(error && typeof error === 'object' && 'code' in error && error.code === 'EADDRINUSE');
+}
+function isLoopbackHost(host) {
+    return host === '127.0.0.1' || host === 'localhost' || host === '::1';
+}
+function constantTimeEqual(left, right) {
+    const leftBuffer = Buffer.from(left);
+    const rightBuffer = Buffer.from(right);
+    if (leftBuffer.length !== rightBuffer.length) {
+        return false;
+    }
+    return timingSafeEqual(leftBuffer, rightBuffer);
+}
+async function readJson(request) {
+    const body = await readBody(request);
+    try {
+        return JSON.parse(body);
+    }
+    catch (error) {
+        throw new BridgeError('InvalidJson', 'Request body is not valid JSON', {
+            status: 400,
+            cause: error,
+        });
+    }
+}
+function readBody(request) {
+    const maxBytes = 1_048_576;
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let totalBytes = 0;
+        request.on('data', (chunk) => {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            totalBytes += buffer.length;
+            if (totalBytes > maxBytes) {
+                reject(new BridgeError('RequestTooLarge', 'Request body exceeds 1 MiB', { status: 413 }));
+                request.destroy();
+                return;
+            }
+            chunks.push(buffer);
+        });
+        request.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        request.on('error', reject);
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/workflow-watch.d.ts

@@ -0,0 +1,31 @@
+import { BridgeError } from './errors.js';
+import type { WorkflowStatusEvent } from './protocol/schema.js';
+export type WorkflowWatchInput = {
+    clientId?: string;
+    workflowId: string;
+    timeoutMs?: number;
+};
+export type WorkflowWatchResult = WorkflowStatusEvent & {
+    timedOut: boolean;
+};
+export type WorkflowWatchConnection = {
+    clientId: string;
+    workflowId: string;
+    onStatus: (listener: (event: WorkflowStatusEvent) => void) => () => void;
+    onClose: (listener: (error: BridgeError) => void) => () => void;
+    close: () => void;
+};
+type WaitForWorkflowStatusOptions = {
+    clientId: string;
+    workflowId: string;
+    subscribe: (onStatus: (event: WorkflowStatusEvent) => void, onClose: (error: BridgeError) => void) => () => void;
+    readStatus: () => Promise<WorkflowStatusEvent>;
+    onStatus?: (event: WorkflowStatusEvent) => void;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+};
+export declare function workflowWatchWebSocketUrl(bridgeUrl: URL): URL;
+export declare function connectWorkflowWatch(url: string | URL, input: Omit<WorkflowWatchInput, 'timeoutMs'>, token?: string, signal?: AbortSignal): Promise<WorkflowWatchConnection>;
+export declare function waitForWorkflowStatus(options: WaitForWorkflowStatusOptions): Promise<WorkflowWatchResult>;
+export {};
+//# sourceMappingURL=workflow-watch.d.ts.map