@kin-tio/cli 0.6.0

package/dist/src/mcp/ipc-host.js

@@ -0,0 +1,275 @@
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import { createServer } from 'node:net';
+import path from 'node:path';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { MCP_FRAME_MAX_BYTES, MCP_HANDSHAKE_ERROR, MCP_HANDSHAKE_OK, createMcpGeneration, ensureMcpStateDirectory, mcpInstanceId, mcpIpcAddress, parseMcpHandshake, readSocketLine, writeMcpDescriptor, } from './ipc-protocol.js';
+function writeLine(socket, value) {
+    return new Promise((resolve, reject) => {
+        socket.write(`${value}\n`, (error) => error ? reject(error) : resolve());
+    });
+}
+export class McpIpcHost {
+    #instanceKey;
+    #stateDirectory;
+    #relayFile;
+    #wechatKf;
+    #memory;
+    #ilink;
+    #logger;
+    #connections = new Set();
+    #server;
+    #descriptor;
+    #descriptorFile = '';
+    #starting;
+    #closing;
+    #force = false;
+    #closed = false;
+    constructor({ instanceKey, stateDirectory, relayFile, wechatKf, memory, ilink, logger = console, }) {
+        this.#instanceKey = path.resolve(instanceKey);
+        this.#stateDirectory = path.join(path.resolve(stateDirectory), '.kintio-mcp', mcpInstanceId(this.#instanceKey));
+        this.#relayFile = path.resolve(relayFile);
+        this.#wechatKf = wechatKf;
+        this.#memory = memory;
+        this.#ilink = ilink;
+        this.#logger = logger;
+    }
+    start() {
+        if (this.#closed)
+            return Promise.reject(new Error('MCP IPC host is closed'));
+        this.#starting ||= this.#start();
+        return this.#starting;
+    }
+    async #start() {
+        let relayStat;
+        try {
+            relayStat = fs.statSync(this.#relayFile);
+        }
+        catch {
+            throw new Error('MCP relay entry is unavailable');
+        }
+        if (!relayStat.isFile())
+            throw new Error('MCP relay entry is not a file');
+        ensureMcpStateDirectory(this.#stateDirectory);
+        this.#removeStaleState();
+        const generation = createMcpGeneration();
+        const descriptor = {
+            version: 1,
+            generation,
+            address: mcpIpcAddress(this.#instanceKey, generation),
+            token: randomBytes(32).toString('base64url'),
+        };
+        const server = createServer((socket) => this.#accept(socket));
+        server.maxConnections = 16;
+        this.#server = server;
+        this.#descriptor = descriptor;
+        try {
+            if (process.platform !== 'win32')
+                fs.rmSync(descriptor.address, { force: true });
+            await new Promise((resolve, reject) => {
+                const failed = (error) => reject(error);
+                server.once('error', failed);
+                server.listen(descriptor.address, () => {
+                    server.off('error', failed);
+                    resolve();
+                });
+            });
+            if (this.#closed)
+                throw new Error('MCP IPC host is closed');
+            if (process.platform !== 'win32')
+                fs.chmodSync(descriptor.address, 0o600);
+            if (this.#closed)
+                throw new Error('MCP IPC host is closed');
+            this.#descriptorFile = writeMcpDescriptor(this.#stateDirectory, descriptor);
+            if (this.#closed)
+                throw new Error('MCP IPC host is closed');
+            server.on('error', () => this.#logger.error('[mcp] IPC listener failed'));
+            return Object.freeze({
+                ...(this.#wechatKf ? { wechatKf: this.#launch('wechat_kf') } : {}),
+                memory: this.#launch('conversation_memory'),
+                ...(this.#ilink ? { ilink: this.#launch('weixin_ilink') } : {}),
+            });
+        }
+        catch (error) {
+            this.#cleanupFiles();
+            await this.#forceClose();
+            await this.#stopServer(server);
+            throw error;
+        }
+    }
+    #launch(route) {
+        return Object.freeze({
+            command: process.execPath,
+            args: Object.freeze([
+                this.#relayFile,
+                '--descriptor',
+                this.#descriptorFile,
+                '--route',
+                route,
+            ]),
+        });
+    }
+    #factory(route) {
+        switch (route) {
+            case 'wechat_kf': return this.#wechatKf;
+            case 'weixin_ilink': return this.#ilink;
+            case 'conversation_memory': return this.#memory;
+        }
+    }
+    #accept(socket) {
+        if (this.#closed) {
+            socket.destroy();
+            return;
+        }
+        socket.setNoDelay(true);
+        let mcp;
+        let closed;
+        let authenticatedRoute = false;
+        const connection = {
+            socket,
+            authenticated: false,
+            close: () => {
+                closed ||= Promise.resolve()
+                    .then(() => mcp?.close())
+                    .finally(() => socket.destroy());
+                return closed;
+            },
+        };
+        this.#connections.add(connection);
+        socket.on('error', () => socket.destroy());
+        socket.once('close', () => {
+            this.#connections.delete(connection);
+            void connection.close().catch(() => undefined);
+        });
+        void (async () => {
+            const descriptor = this.#descriptor;
+            if (this.#closed || !descriptor)
+                throw new Error('MCP IPC host unavailable');
+            const route = parseMcpHandshake(await readSocketLine(socket), descriptor);
+            if (this.#closed)
+                throw new Error('MCP IPC host unavailable');
+            const factory = route ? this.#factory(route) : undefined;
+            if (!factory) {
+                await writeLine(socket, MCP_HANDSHAKE_ERROR).catch(() => undefined);
+                socket.destroy();
+                return;
+            }
+            authenticatedRoute = true;
+            mcp = factory();
+            const transport = new StdioServerTransport(socket, socket, {
+                maxBufferSize: MCP_FRAME_MAX_BYTES,
+            });
+            transport.onerror = () => socket.destroy();
+            transport.onclose = () => socket.destroy();
+            await writeLine(socket, MCP_HANDSHAKE_OK);
+            if (this.#closed)
+                throw new Error('MCP IPC host unavailable');
+            await mcp.connect(transport);
+            if (this.#closed) {
+                await connection.close();
+                return;
+            }
+            connection.authenticated = true;
+            socket.resume();
+        })().catch(() => {
+            if (authenticatedRoute && !this.#closed) {
+                this.#logger.error('[mcp] authenticated IPC connection failed');
+            }
+            socket.destroy();
+        });
+    }
+    close(force = false) {
+        if (force)
+            this.#force = true;
+        if (!this.#closing) {
+            this.#closed = true;
+            this.#cleanupFiles();
+            void this.#closeUnauthenticated();
+            this.#closing = this.#finishClose();
+        }
+        if (force)
+            void this.#forceClose();
+        return this.#closing;
+    }
+    async #finishClose() {
+        await this.#starting?.catch(() => undefined);
+        this.#cleanupFiles();
+        const server = this.#server;
+        if (!server)
+            return;
+        const stopped = this.#stopServer(server);
+        if (this.#force)
+            await this.#forceClose();
+        else
+            await this.#closeUnauthenticated();
+        await stopped;
+        this.#cleanupFiles();
+    }
+    #stopServer(server) {
+        if (!server.listening)
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            server.close((error) => error ? reject(error) : resolve());
+        });
+    }
+    async #closeUnauthenticated() {
+        await Promise.allSettled([...this.#connections]
+            .filter((connection) => !connection.authenticated)
+            .map((connection) => connection.close()));
+    }
+    async #forceClose() {
+        await Promise.allSettled([...this.#connections].map((connection) => connection.close()));
+    }
+    #cleanupFiles() {
+        if (this.#descriptorFile)
+            fs.rmSync(this.#descriptorFile, { force: true });
+        if (this.#descriptor && process.platform !== 'win32') {
+            fs.rmSync(this.#descriptor.address, { force: true });
+            try {
+                fs.rmdirSync(path.dirname(this.#descriptor.address));
+            }
+            catch (error) {
+                const code = error.code;
+                if (code !== 'ENOENT' && code !== 'ENOTEMPTY')
+                    throw error;
+            }
+        }
+    }
+    #removeStaleState() {
+        const pattern = /^mcp-runtime-([A-Za-z0-9_-]{24})\.json$/u;
+        for (const name of fs.readdirSync(this.#stateDirectory)) {
+            const generation = pattern.exec(name)?.[1];
+            if (!generation)
+                continue;
+            fs.rmSync(path.join(this.#stateDirectory, name), { force: true });
+            if (process.platform !== 'win32') {
+                fs.rmSync(mcpIpcAddress(this.#instanceKey, generation), { force: true });
+            }
+        }
+        if (process.platform !== 'win32') {
+            const socketDirectory = path.dirname(mcpIpcAddress(this.#instanceKey, 'a'.repeat(24)));
+            ensureMcpStateDirectory(socketDirectory);
+            const uid = process.getuid?.();
+            for (const name of fs.readdirSync(socketDirectory)) {
+                if (!name.endsWith('.sock'))
+                    continue;
+                const generation = name.slice(0, -'.sock'.length);
+                if (!/^[A-Za-z0-9_-]{24}$/u.test(generation))
+                    continue;
+                const socketPath = path.join(socketDirectory, name);
+                let stat;
+                try {
+                    stat = fs.lstatSync(socketPath);
+                }
+                catch (error) {
+                    if (error.code === 'ENOENT')
+                        continue;
+                    throw error;
+                }
+                if (!stat.isSocket() || (uid !== undefined && stat.uid !== uid))
+                    continue;
+                fs.rmSync(socketPath, { force: true });
+            }
+        }
+    }
+}

package/dist/src/mcp/ipc-protocol.js

@@ -0,0 +1,226 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { ensurePrivateDirectory } from '../lib/private-directory.js';
+import { canonicalPath } from '../lib/path-identity.js';
+const MCP_ROUTES = [
+    'wechat_kf',
+    'weixin_ilink',
+    'conversation_memory',
+];
+export const MCP_FRAME_MAX_BYTES = 256 * 1024;
+export const MCP_HANDSHAKE_OK = 'KINTIO-MCP/1 OK';
+export const MCP_HANDSHAKE_ERROR = 'KINTIO-MCP/1 ERROR';
+const DESCRIPTOR_MAX_BYTES = 4 * 1024;
+const HANDSHAKE_MAX_BYTES = 512;
+const HANDSHAKE_TIMEOUT_MS = 2_000;
+const GENERATION_PATTERN = /^[A-Za-z0-9_-]{24}$/u;
+const TOKEN_PATTERN = /^[A-Za-z0-9_-]{43}$/u;
+const DESCRIPTOR_PREFIX = 'mcp-runtime-';
+export function createMcpGeneration() {
+    return randomBytes(18).toString('base64url');
+}
+export function mcpDescriptorPath(directory, generation) {
+    if (!GENERATION_PATTERN.test(generation))
+        throw new Error('Invalid MCP generation');
+    return path.join(path.resolve(directory), `${DESCRIPTOR_PREFIX}${generation}.json`);
+}
+export function mcpIpcAddress(instanceKey, generation, platform = process.platform) {
+    if (!GENERATION_PATTERN.test(generation))
+        throw new Error('Invalid MCP generation');
+    const instance = mcpInstanceId(instanceKey);
+    const name = `kintio-mcp-${instance}-${generation}`;
+    return platform === 'win32'
+        ? `\\\\.\\pipe\\${name}`
+        : path.posix.join('/tmp', `kintio-mcp-${instance}`, `${generation}.sock`);
+}
+export function mcpInstanceId(instanceKey) {
+    return createHash('sha256').update(canonicalPath(instanceKey)).digest('hex').slice(0, 16);
+}
+export function ensureMcpStateDirectory(directory) {
+    const target = ensurePrivateDirectory(directory);
+    assertPrivateDirectory(target);
+    return target;
+}
+function parseDescriptor(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('Invalid MCP descriptor');
+    }
+    const record = value;
+    if (Object.keys(record).sort().join(',') !== 'address,generation,token,version' ||
+        record.version !== 1 ||
+        typeof record.generation !== 'string' ||
+        !GENERATION_PATTERN.test(record.generation) ||
+        typeof record.address !== 'string' ||
+        !record.address ||
+        record.address.length > 512 ||
+        record.address.includes('\0') ||
+        !isMcpIpcAddress(record.address, record.generation) ||
+        typeof record.token !== 'string' ||
+        !TOKEN_PATTERN.test(record.token))
+        throw new Error('Invalid MCP descriptor');
+    return Object.freeze({
+        version: 1,
+        generation: record.generation,
+        address: record.address,
+        token: record.token,
+    });
+}
+export function writeMcpDescriptor(directory, descriptor) {
+    const target = mcpDescriptorPath(ensureMcpStateDirectory(directory), descriptor.generation);
+    const source = `${JSON.stringify(parseDescriptor(descriptor))}\n`;
+    fs.writeFileSync(target, source, { flag: 'wx', mode: 0o600 });
+    try {
+        fs.chmodSync(target, 0o600);
+    }
+    catch (error) {
+        fs.rmSync(target, { force: true });
+        throw error;
+    }
+    return target;
+}
+export function readMcpDescriptor(filePath) {
+    const target = path.resolve(filePath);
+    assertPrivateDirectory(path.dirname(target));
+    const before = fs.lstatSync(target);
+    if (!before.isFile() || before.isSymbolicLink())
+        throw new Error('Unsafe MCP descriptor');
+    const noFollow = process.platform === 'win32' ? 0 : fs.constants.O_NOFOLLOW;
+    const descriptor = fs.openSync(target, fs.constants.O_RDONLY | noFollow);
+    try {
+        const stat = fs.fstatSync(descriptor);
+        assertSafeDescriptor(before, stat);
+        const buffer = Buffer.allocUnsafe(DESCRIPTOR_MAX_BYTES + 1);
+        const bytesRead = fs.readSync(descriptor, buffer, 0, buffer.length, null);
+        if (bytesRead === 0 || bytesRead > DESCRIPTOR_MAX_BYTES) {
+            throw new Error('Unsafe MCP descriptor');
+        }
+        const parsed = parseDescriptor(JSON.parse(buffer.subarray(0, bytesRead).toString('utf8')));
+        if (target !== mcpDescriptorPath(path.dirname(target), parsed.generation)) {
+            throw new Error('Unsafe MCP descriptor');
+        }
+        return parsed;
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
+export function mcpHandshake(descriptor, route) {
+    return `${JSON.stringify({
+        version: descriptor.version,
+        generation: descriptor.generation,
+        route,
+        token: descriptor.token,
+    })}\n`;
+}
+export function parseMcpHandshake(source, descriptor) {
+    try {
+        const value = JSON.parse(source);
+        if (!value || typeof value !== 'object' || Array.isArray(value) ||
+            Object.keys(value).sort().join(',') !== 'generation,route,token,version' ||
+            value.version !== 1 ||
+            value.generation !== descriptor.generation ||
+            typeof value.route !== 'string' ||
+            !MCP_ROUTES.includes(value.route) ||
+            typeof value.token !== 'string')
+            return undefined;
+        const presented = Buffer.from(value.token);
+        const expected = Buffer.from(descriptor.token);
+        return presented.length === expected.length && timingSafeEqual(presented, expected)
+            ? value.route
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readSocketLine(socket) {
+    return new Promise((resolve, reject) => {
+        let buffer = Buffer.alloc(0);
+        let settled = false;
+        const cleanup = () => {
+            clearTimeout(timer);
+            socket.off('data', onData);
+            socket.off('error', onError);
+            socket.off('end', onEnd);
+            socket.off('close', onClose);
+        };
+        const finish = (error, line = '') => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            if (error)
+                reject(error);
+            else
+                resolve(line);
+        };
+        const onError = () => finish(new Error('MCP IPC handshake failed'));
+        const onEnd = () => finish(new Error('MCP IPC handshake ended'));
+        const onClose = () => finish(new Error('MCP IPC handshake closed'));
+        const onData = (chunk) => {
+            const data = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+            const newline = data.indexOf(0x0a);
+            if (newline < 0) {
+                if (buffer.length + data.length > HANDSHAKE_MAX_BYTES) {
+                    finish(new Error('MCP IPC handshake too large'));
+                    return;
+                }
+                buffer = Buffer.concat([buffer, data], buffer.length + data.length);
+                return;
+            }
+            const lineBytes = buffer.length + newline;
+            if (lineBytes > HANDSHAKE_MAX_BYTES) {
+                finish(new Error('MCP IPC handshake too large'));
+                return;
+            }
+            const line = buffer.length
+                ? Buffer.concat([buffer, data.subarray(0, newline)], lineBytes)
+                : data.subarray(0, newline);
+            const remainder = data.subarray(newline + 1);
+            socket.pause();
+            if (remainder.length)
+                socket.unshift(remainder);
+            finish(undefined, line.toString('utf8').replace(/\r$/u, ''));
+        };
+        const timer = setTimeout(() => finish(new Error('MCP IPC handshake timed out')), HANDSHAKE_TIMEOUT_MS);
+        timer.unref?.();
+        socket.on('data', onData);
+        socket.once('error', onError);
+        socket.once('end', onEnd);
+        socket.once('close', onClose);
+        socket.resume();
+    });
+}
+export function isMcpRoute(value) {
+    return MCP_ROUTES.includes(value);
+}
+function assertPrivateDirectory(directory) {
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error('Unsafe MCP state directory');
+    }
+    if (process.platform !== 'win32') {
+        const uid = process.getuid?.();
+        if ((uid !== undefined && stat.uid !== uid) || (stat.mode & 0o077) !== 0) {
+            throw new Error('Unsafe MCP state directory');
+        }
+    }
+}
+function assertSafeDescriptor(before, opened) {
+    if (!opened.isFile() || opened.size <= 0 || opened.size > DESCRIPTOR_MAX_BYTES ||
+        before.dev !== opened.dev || before.ino !== opened.ino)
+        throw new Error('Unsafe MCP descriptor');
+    if (process.platform !== 'win32') {
+        const uid = process.getuid?.();
+        if ((uid !== undefined && opened.uid !== uid) || (opened.mode & 0o077) !== 0) {
+            throw new Error('Unsafe MCP descriptor');
+        }
+    }
+}
+function isMcpIpcAddress(value, generation) {
+    const match = process.platform === 'win32'
+        ? /^\\\\\.\\pipe\\kintio-mcp-[a-f0-9]{16}-([A-Za-z0-9_-]{24})$/u.exec(value)
+        : /^\/tmp\/kintio-mcp-[a-f0-9]{16}\/([A-Za-z0-9_-]{24})\.sock$/u.exec(value);
+    return match?.[1] === generation;
+}

package/dist/src/mcp/stdio-relay.js

@@ -0,0 +1,122 @@
+import { createConnection } from 'node:net';
+import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { MCP_HANDSHAKE_OK, isMcpRoute, mcpHandshake, readMcpDescriptor, readSocketLine, } from './ipc-protocol.js';
+const CONNECT_TIMEOUT_MS = 2_000;
+export const MCP_RELAY_ERROR = 'Kintio MCP relay failed\n';
+export function parseMcpRelayArgs(args) {
+    if (args.length !== 4 ||
+        args[0] !== '--descriptor' ||
+        args[2] !== '--route' ||
+        !args[1] ||
+        !path.isAbsolute(args[1]) ||
+        args[1].includes('\0') ||
+        !args[3] ||
+        !isMcpRoute(args[3]))
+        throw new Error('Invalid MCP relay arguments');
+    return Object.freeze({
+        descriptorFile: path.resolve(args[1]),
+        route: args[3],
+    });
+}
+export async function runMcpRelay(args, streams) {
+    const options = parseMcpRelayArgs(args);
+    const descriptor = readMcpDescriptor(options.descriptorFile);
+    const socket = await connectIpc(descriptor.address);
+    try {
+        await writeSocket(socket, mcpHandshake(descriptor, options.route));
+        if (await readSocketLine(socket) !== MCP_HANDSHAKE_OK) {
+            throw new Error('MCP relay authentication failed');
+        }
+        await relayBytes(socket, streams);
+    }
+    finally {
+        socket.destroy();
+    }
+}
+async function connectIpc(address) {
+    const socket = createConnection({ path: address });
+    // Keep the dedicated relay process fail-closed even if an error occurs in the
+    // small gaps between the connect, handshake, and stream pipeline listeners.
+    socket.on('error', () => undefined);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.off('connect', onConnect);
+            socket.off('error', onError);
+            socket.off('close', onClose);
+            if (error) {
+                socket.destroy();
+                reject(error);
+            }
+            else {
+                resolve(socket);
+            }
+        };
+        const onConnect = () => finish();
+        const onError = () => finish(new Error('MCP IPC connection failed'));
+        const onClose = () => finish(new Error('MCP IPC connection closed'));
+        const timer = setTimeout(() => finish(new Error('MCP IPC connection timed out')), CONNECT_TIMEOUT_MS);
+        timer.unref?.();
+        socket.once('connect', onConnect);
+        socket.once('error', onError);
+        socket.once('close', onClose);
+    });
+}
+function writeSocket(socket, source) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.off('error', onError);
+            socket.off('close', onClose);
+            if (error)
+                reject(new Error('MCP IPC write failed'));
+            else
+                resolve();
+        };
+        const onError = () => finish(new Error('MCP IPC write failed'));
+        const onClose = () => finish(new Error('MCP IPC write closed'));
+        socket.once('error', onError);
+        socket.once('close', onClose);
+        socket.write(source, finish);
+    });
+}
+async function relayBytes(socket, { input, output }) {
+    const controller = new AbortController();
+    const upstream = pipeline(input, socket, {
+        end: false,
+        signal: controller.signal,
+    });
+    const downstream = pipeline(socket, output, { signal: controller.signal });
+    try {
+        const first = await Promise.race([
+            upstream.then(() => 'input'),
+            downstream.then(() => 'socket'),
+        ]);
+        if (first === 'input') {
+            socket.end();
+            await downstream;
+            return;
+        }
+        // The MCP host ended first. Stop waiting on a still-open parent stdin.
+        controller.abort();
+        input.destroy();
+        void upstream.catch(() => undefined);
+    }
+    catch {
+        controller.abort();
+        input.destroy();
+        output.destroy();
+        socket.destroy();
+        void upstream.catch(() => undefined);
+        void downstream.catch(() => undefined);
+        throw new Error('MCP stdio relay failed');
+    }
+}