@hcu-lab.me/mcp-device 1.0.0

package/dist/device/linux-service.js

@@ -0,0 +1,268 @@
+import { execFile as execFileCallback } from 'child_process';
+import fs from 'fs/promises';
+import os from 'os';
+import path from 'path';
+import readline from 'readline/promises';
+import { promisify } from 'util';
+const execFileAsync = promisify(execFileCallback);
+const SYSTEMD_UNIT = 'mcp-device.service';
+const SYSTEMD_OWNER_MARKER = '# Managed by MCP Device';
+const PM2_NAME = 'mcp-device';
+async function defaultExecFile(file, args) {
+    const result = await execFileAsync(file, args, { windowsHide: true, encoding: 'utf8' });
+    return { stdout: String(result.stdout || ''), stderr: String(result.stderr || '') };
+}
+function quoteSystemdArg(value) {
+    if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(value))
+        return value;
+    return `"${value.replace(/([\\"])/g, '\\$1')}"`;
+}
+function defaultUnitPath() {
+    const configHome = String(process.env.XDG_CONFIG_HOME || '').trim() || path.join(os.homedir(), '.config');
+    return path.join(configHome, 'systemd', 'user', SYSTEMD_UNIT);
+}
+function guidance() {
+    return 'Run `pm2 startup` for this user and complete the printed setup, then retry; or choose the systemd-user alternative.';
+}
+export async function chooseLinuxManager({ ask } = {}) {
+    let answer;
+    if (ask)
+        answer = await ask();
+    else {
+        if (!process.stdin.isTTY || !process.stdout.isTTY) {
+            throw new Error('Linux install requires an interactive manager choice: systemd-user or PM2.');
+        }
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        try {
+            answer = await rl.question('Background manager [systemd/pm2] (systemd): ');
+        }
+        finally {
+            rl.close();
+        }
+    }
+    const value = String(answer || '').trim().toLowerCase();
+    if (!value || ['systemd', 'systemd-user', 'systemd_user', '1'].includes(value))
+        return 'systemd';
+    if (['pm2', '2'].includes(value))
+        return 'pm2';
+    throw new Error('Choose `systemd` or `pm2`.');
+}
+export class SystemdUserDeviceService {
+    constructor(options = {}) {
+        this.platform = options.platform || process.platform;
+        this.execFile = options.execFile || defaultExecFile;
+        this.unitPath = path.resolve(options.unitPath || defaultUnitPath());
+        this.nodePath = options.platform === 'linux' && options.nodePath ? String(options.nodePath) : path.resolve(options.nodePath || process.execPath);
+        this.entrypoint = options.platform === 'linux' && options.entrypoint ? String(options.entrypoint) : path.resolve(options.entrypoint || process.argv[1]);
+        this.pathValue = String(options.pathValue ?? process.env.PATH ?? '/usr/local/bin:/usr/bin:/bin');
+    }
+    assertLinux() {
+        if (this.platform !== 'linux')
+            throw new Error('systemd-user lifecycle is supported on Linux only.');
+    }
+    async unitExists() {
+        try {
+            return (await fs.stat(this.unitPath)).isFile();
+        }
+        catch (error) {
+            if (error?.code === 'ENOENT')
+                return false;
+            throw error;
+        }
+    }
+    async assertOwnedUnitIfPresent() {
+        if (!await this.unitExists())
+            return false;
+        const text = await fs.readFile(this.unitPath, 'utf8');
+        if (!text.includes(SYSTEMD_OWNER_MARKER)) {
+            throw new Error(`systemd ownership conflict: ${this.unitPath} is not owned by MCP Device.`);
+        }
+        return true;
+    }
+    unitText() {
+        return [
+            SYSTEMD_OWNER_MARKER,
+            '[Unit]',
+            'Description=MCP Device',
+            'After=network-online.target',
+            '',
+            '[Service]',
+            'Type=simple',
+            `Environment="PATH=${this.pathValue.replace(/["\\]/g, match => `\\${match}`)}"`,
+            `ExecStart=${quoteSystemdArg(this.nodePath)} ${quoteSystemdArg(this.entrypoint)} --service --manager=systemd`,
+            'Restart=on-failure',
+            'RestartSec=3',
+            '',
+            '[Install]',
+            'WantedBy=default.target',
+            ''
+        ].join('\n');
+    }
+    async install() {
+        this.assertLinux();
+        await this.assertOwnedUnitIfPresent();
+        await this.execFile('systemctl', ['--user', 'show-environment']);
+        await fs.mkdir(path.dirname(this.unitPath), { recursive: true });
+        await fs.writeFile(this.unitPath, this.unitText(), { mode: 0o600 });
+        await this.execFile('systemctl', ['--user', 'daemon-reload']);
+        await this.execFile('systemctl', ['--user', 'enable', '--now', SYSTEMD_UNIT]);
+        const status = await this.status();
+        if (!status.autostart || !status.running)
+            throw new Error('systemd-user did not become enabled and active.');
+    }
+    async stop() {
+        this.assertLinux();
+        if (await this.assertOwnedUnitIfPresent())
+            await this.execFile('systemctl', ['--user', 'stop', SYSTEMD_UNIT]);
+    }
+    async status() {
+        this.assertLinux();
+        if (!await this.assertOwnedUnitIfPresent())
+            return { installed: false, running: false, autostart: false, manager: 'systemd' };
+        let autostart = false;
+        let running = false;
+        try {
+            autostart = /enabled|static/i.test(String((await this.execFile('systemctl', ['--user', 'is-enabled', SYSTEMD_UNIT])).stdout));
+        }
+        catch { }
+        try {
+            running = /^active$/i.test(String((await this.execFile('systemctl', ['--user', 'is-active', SYSTEMD_UNIT])).stdout).trim());
+        }
+        catch { }
+        return { installed: true, running, autostart, manager: 'systemd' };
+    }
+    async uninstall() {
+        this.assertLinux();
+        if (await this.assertOwnedUnitIfPresent()) {
+            try {
+                await this.execFile('systemctl', ['--user', 'disable', '--now', SYSTEMD_UNIT]);
+            }
+            catch { }
+            await fs.rm(this.unitPath, { force: true });
+            await this.execFile('systemctl', ['--user', 'daemon-reload']);
+        }
+    }
+}
+export class Pm2DeviceService {
+    constructor(options = {}) {
+        this.platform = options.platform || process.platform;
+        this.execFile = options.execFile || defaultExecFile;
+        this.pm2Path = options.pm2Path || 'pm2';
+        this.nodePath = options.platform === 'linux' && options.nodePath ? String(options.nodePath) : path.resolve(options.nodePath || process.execPath);
+        this.entrypoint = options.platform === 'linux' && options.entrypoint ? String(options.entrypoint) : path.resolve(options.entrypoint || process.argv[1]);
+        this.user = String(options.user || process.env.USER || process.env.LOGNAME || os.userInfo().username);
+        this.pm2Home = options.platform === 'linux' && options.pm2Home ? String(options.pm2Home) : path.resolve(options.pm2Home || process.env.PM2_HOME || path.join(os.homedir(), '.pm2'));
+    }
+    assertLinux() {
+        if (this.platform !== 'linux')
+            throw new Error('PM2 lifecycle is supported on Linux only.');
+    }
+    async processRow() {
+        let rows;
+        try {
+            rows = JSON.parse(String((await this.execFile(this.pm2Path, ['jlist'])).stdout || '[]'));
+        }
+        catch {
+            return null;
+        }
+        return Array.isArray(rows) ? rows.find(item => item?.name === PM2_NAME) || null : null;
+    }
+    assertOwnedProcess(row) {
+        if (!row)
+            return;
+        const env = row?.pm2_env || {};
+        const execPath = String(env.pm_exec_path || '').replace(/\\/g, '/');
+        const interpreter = String(env.exec_interpreter || '').replace(/\\/g, '/');
+        const args = Array.isArray(env.args) ? env.args.map((value) => String(value)) : [];
+        if (execPath !== this.entrypoint.replace(/\\/g, '/') ||
+            interpreter !== this.nodePath.replace(/\\/g, '/') ||
+            !args.includes('--service') || !args.includes('--manager=pm2')) {
+            throw new Error('PM2 ownership conflict: process named mcp-device is not owned by this MCP Device installation.');
+        }
+    }
+    async proveStartup() {
+        this.assertLinux();
+        try {
+            await this.execFile(this.pm2Path, ['--version']);
+        }
+        catch {
+            throw new Error(`PM2 is not available for the current user. ${guidance()}`);
+        }
+        const unit = `pm2-${this.user}.service`;
+        let evidence = '';
+        try {
+            evidence = String((await this.execFile('systemctl', ['show', unit, '--property=FragmentPath,ExecStart,Environment', '--no-pager'])).stdout || '');
+        }
+        catch {
+            try {
+                evidence = String((await this.execFile('systemctl', ['--user', 'show', unit, '--property=FragmentPath,ExecStart,Environment', '--no-pager'])).stdout || '');
+            }
+            catch {
+                throw new Error(`PM2 startup integration is not proven. ${guidance()}`);
+            }
+        }
+        const normalized = evidence.replace(/\\/g, '/');
+        const home = this.pm2Home.replace(/\\/g, '/');
+        if (!/pm2/i.test(normalized) || !/resurrect/i.test(normalized) || !normalized.includes(home)) {
+            throw new Error(`PM2 startup integration does not match this user/PM2_HOME. ${guidance()}`);
+        }
+    }
+    async install() {
+        await this.proveStartup();
+        const existing = await this.processRow();
+        this.assertOwnedProcess(existing);
+        if (!existing) {
+            await this.execFile(this.pm2Path, ['start', this.entrypoint, '--name', PM2_NAME, '--interpreter', this.nodePath, '--', '--service', '--manager=pm2']);
+        }
+        else if (String(existing?.pm2_env?.status || '').toLowerCase() !== 'online') {
+            await this.execFile(this.pm2Path, ['restart', PM2_NAME]);
+        }
+        await this.execFile(this.pm2Path, ['save']);
+        const status = await this.status();
+        if (!status.running)
+            throw new Error('PM2 process did not become online.');
+    }
+    async stop() {
+        this.assertLinux();
+        const row = await this.processRow();
+        this.assertOwnedProcess(row);
+        if (row)
+            await this.execFile(this.pm2Path, ['stop', PM2_NAME]);
+    }
+    async status() {
+        this.assertLinux();
+        const row = await this.processRow();
+        if (!row)
+            return { installed: false, running: false, autostart: true, manager: 'pm2' };
+        this.assertOwnedProcess(row);
+        return {
+            installed: true,
+            running: String(row?.pm2_env?.status || '').toLowerCase() === 'online',
+            autostart: true,
+            manager: 'pm2'
+        };
+    }
+    async uninstall() {
+        this.assertLinux();
+        const row = await this.processRow();
+        this.assertOwnedProcess(row);
+        if (!row)
+            return;
+        await this.execFile(this.pm2Path, ['delete', PM2_NAME]);
+        await this.execFile(this.pm2Path, ['save']);
+    }
+}
+export async function discoverLinuxManagers(options = {}) {
+    if (process.platform !== 'linux')
+        return [];
+    const systemd = options.systemd || new SystemdUserDeviceService();
+    const pm2 = options.pm2 || new Pm2DeviceService();
+    const results = [];
+    const systemdStatus = await systemd.status().catch(() => ({ installed: false, running: false, autostart: false, manager: 'systemd' }));
+    const pm2Status = await pm2.status().catch(() => ({ installed: false, running: false, autostart: false, manager: 'pm2' }));
+    if (systemdStatus.installed)
+        results.push(systemdStatus);
+    if (pm2Status.installed)
+        results.push(pm2Status);
+    return results;
+}

package/dist/device/official-trust.d.ts

@@ -0,0 +1,7 @@
+import { GatewayDeviceConfigStore, type GatewayDeviceConfig } from './gateway-config.js';
+export declare const OFFICIAL_GATEWAY_URL = "https://mcp-v2.hcu-lab.me/mcp";
+export declare function isOfficialGatewayUrl(value: string | null | undefined): boolean;
+export declare function bootstrapOfficialGatewayTrust(store: GatewayDeviceConfigStore, options?: {
+    gatewayUrl?: string | null;
+    caPath?: string;
+}): Promise<GatewayDeviceConfig>;

package/dist/device/official-trust.js

@@ -0,0 +1,49 @@
+import { X509Certificate } from 'crypto';
+import fs from 'fs/promises';
+import { fileURLToPath } from 'url';
+export const OFFICIAL_GATEWAY_URL = 'https://mcp-v2.hcu-lab.me/mcp';
+function normalizedUrl(value) {
+    return new URL(value).toString();
+}
+function defaultOfficialCaPath() {
+    return fileURLToPath(new URL('../data/official-app-ca.pem', import.meta.url));
+}
+export function isOfficialGatewayUrl(value) {
+    if (!value)
+        return false;
+    try {
+        return normalizedUrl(value) === normalizedUrl(OFFICIAL_GATEWAY_URL);
+    }
+    catch {
+        return false;
+    }
+}
+export async function bootstrapOfficialGatewayTrust(store, options = {}) {
+    const current = await store.load();
+    const gatewayUrl = String(process.env.MCP_GATEWAY_URL || options.gatewayUrl || current.gatewayUrl || OFFICIAL_GATEWAY_URL).trim();
+    if (!isOfficialGatewayUrl(gatewayUrl)) {
+        if (isOfficialGatewayUrl(current.gatewayUrl) && current.appCaPem) {
+            return await store.update({ gatewayUrl, appCaPem: null });
+        }
+        return await store.update({ gatewayUrl });
+    }
+    if (current.appCaPem && current.securityProtocolFloor >= 2 && isOfficialGatewayUrl(current.gatewayUrl || gatewayUrl)) {
+        return current;
+    }
+    const caPath = options.caPath || defaultOfficialCaPath();
+    let appCaPem;
+    try {
+        appCaPem = await fs.readFile(caPath, 'utf8');
+        const certificate = new X509Certificate(appCaPem);
+        if (!certificate.ca)
+            throw new Error('certificate is not a CA');
+    }
+    catch (error) {
+        throw new Error(`Official MCP Device application CA is not provisioned in this package; refusing network bootstrap: ${error?.message || error}`);
+    }
+    return await store.update({
+        gatewayUrl: OFFICIAL_GATEWAY_URL,
+        appCaPem,
+        securityProtocolFloor: 2
+    });
+}

package/dist/device/project-inspection.d.ts

@@ -0,0 +1 @@
+export declare function inspectProjectOnDevice(root: string, args?: any): Promise<any>;

package/dist/device/project-inspection.js

@@ -0,0 +1,180 @@
+import { execFile } from 'child_process';
+import { createHash } from 'crypto';
+import fs from 'fs/promises';
+import path from 'path';
+import { promisify } from 'util';
+const execFileAsync = promisify(execFile);
+const DEFAULT_EXCLUDES = new Set(['.git', 'node_modules', 'logs', 'packages', '_zip_temp']);
+const DEFAULT_TREE_LIMIT = 200;
+const MAX_TREE_LIMIT = 500;
+const DEFAULT_TREE_DEPTH = 3;
+const MAX_TREE_DEPTH = 10;
+const CURSOR_VERSION = 1;
+const MAX_PROJECT_FILE_BYTES = 32 * 1024;
+const VIEWS = new Set(['summary', 'tree', 'git_status', 'git_diff', 'readme', 'package', 'file']);
+function boundedInteger(value, fallback, min, max, label) {
+    if (value === undefined || value === null || value === '')
+        return fallback;
+    const number = Number(value);
+    if (!Number.isInteger(number) || number < min || number > max) {
+        throw new Error(`Invalid ${label}: ${value}. Expected an integer from ${min} to ${max}.`);
+    }
+    return number;
+}
+function cursorVersion(projectId, depth) {
+    return createHash('sha256').update(`project-tree\n${projectId}\n${depth}`).digest('base64url').slice(0, 16);
+}
+function encodeCursor(offset, version) {
+    return Buffer.from(JSON.stringify({ v: CURSOR_VERSION, kind: 'project-tree', offset, version }), 'utf8').toString('base64url');
+}
+function decodeCursor(cursor, version) {
+    if (!cursor)
+        return 0;
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(String(cursor), 'base64url').toString('utf8'));
+    }
+    catch {
+        throw new Error('Invalid cursor: expected an opaque cursor returned by the previous page.');
+    }
+    if (parsed?.v !== CURSOR_VERSION || parsed?.kind !== 'project-tree' || parsed?.version !== version || !Number.isInteger(parsed?.offset) || parsed.offset < 0) {
+        throw new Error('Invalid or stale cursor: request parameters or catalog version changed.');
+    }
+    return parsed.offset;
+}
+async function exists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function resolveInsideRoot(root, relativePath) {
+    const relative = String(relativePath || '').trim();
+    if (!relative || path.isAbsolute(relative) || relative.split(/[\\/]+/).includes('..')) {
+        throw new Error('Invalid project-relative resource path.');
+    }
+    const canonicalRoot = await fs.realpath(root);
+    const candidate = await fs.realpath(path.resolve(canonicalRoot, relative));
+    const rel = path.relative(canonicalRoot, candidate);
+    if (rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+        throw new Error('Resource path escapes project root.');
+    }
+    return candidate;
+}
+function looksBinary(buffer) {
+    return buffer.subarray(0, Math.min(buffer.length, 4096)).includes(0);
+}
+async function collectTreeEntries(root, maxDepth, stopAfter) {
+    const entries = [];
+    async function walk(dir, depth, relativeDir = '') {
+        if (entries.length >= stopAfter || depth > maxDepth)
+            return;
+        const dirEntries = (await fs.readdir(dir, { withFileTypes: true }))
+            .filter(entry => !DEFAULT_EXCLUDES.has(entry.name))
+            .sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of dirEntries) {
+            if (entries.length >= stopAfter)
+                return;
+            const relativePath = relativeDir ? `${relativeDir}/${entry.name}` : entry.name;
+            const isDirectory = entry.isDirectory();
+            entries.push({ path: relativePath, name: entry.name, type: isDirectory ? 'directory' : 'file', depth });
+            if (isDirectory && depth < maxDepth)
+                await walk(path.join(dir, entry.name), depth + 1, relativePath);
+        }
+    }
+    await walk(root, 1);
+    return entries;
+}
+async function execGitRead(cwd, args) {
+    try {
+        const { stdout, stderr } = await execFileAsync('git', args, { cwd, timeout: 30000, windowsHide: true, maxBuffer: 1024 * 1024, encoding: 'utf8' });
+        return { ok: true, stdout: String(stdout || ''), stderr: String(stderr || ''), exitCode: 0 };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            stdout: String(error?.stdout || ''),
+            stderr: String(error?.stderr || error?.message || ''),
+            exitCode: Number.isInteger(error?.code) ? error.code : 1
+        };
+    }
+}
+export async function inspectProjectOnDevice(root, args = {}) {
+    const view = String(args.view || 'summary');
+    if (!VIEWS.has(view))
+        throw new Error(`Invalid project inspection view: ${view}.`);
+    const projectId = String(args.project_id || '').trim();
+    if (view === 'summary') {
+        return {
+            defaultRootName: path.basename(root) || projectId,
+            hasPackageJson: await exists(path.join(root, 'package.json')),
+            hasReadme: await exists(path.join(root, 'README.md')) || await exists(path.join(root, 'README.vi.md'))
+        };
+    }
+    if (view === 'tree') {
+        const depth = boundedInteger(args.depth, DEFAULT_TREE_DEPTH, 1, MAX_TREE_DEPTH, 'depth');
+        const limit = boundedInteger(args.limit, DEFAULT_TREE_LIMIT, 1, MAX_TREE_LIMIT, 'limit');
+        const version = cursorVersion(projectId, depth);
+        const offset = decodeCursor(args.cursor, version);
+        const entries = await collectTreeEntries(root, depth, offset + limit + 1);
+        if (offset > entries.length)
+            throw new Error('Invalid or stale cursor: tree offset is outside the current result set.');
+        const page = entries.slice(offset, offset + limit);
+        const truncated = entries.length > offset + page.length;
+        return {
+            rootName: path.basename(root),
+            maxDepth: depth,
+            maxEntries: limit,
+            entries: page,
+            truncated,
+            nextCursor: truncated ? encodeCursor(offset + page.length, version) : null
+        };
+    }
+    if (view === 'git_status') {
+        const result = await execGitRead(root, ['status', '--short', '--branch']);
+        return { ok: result.ok, status: result.stdout, stderr: result.stderr, exitCode: result.exitCode };
+    }
+    if (view === 'git_diff') {
+        const staged = args.staged === true;
+        const result = await execGitRead(root, staged ? ['diff', '--staged'] : ['diff']);
+        return { ok: result.ok, staged, text: result.ok ? result.stdout : result.stderr, stderr: result.stderr, exitCode: result.exitCode };
+    }
+    if (view === 'readme') {
+        for (const fileName of ['README.md', 'README.vi.md']) {
+            try {
+                const filePath = await resolveInsideRoot(root, fileName);
+                return { fileName, text: await fs.readFile(filePath, 'utf8') };
+            }
+            catch (error) {
+                if (error?.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        throw new Error(`README not found for project_id: ${projectId}`);
+    }
+    if (view === 'package') {
+        let packagePath;
+        try {
+            packagePath = await resolveInsideRoot(root, 'package.json');
+        }
+        catch (error) {
+            if (error?.code === 'ENOENT')
+                throw new Error(`package.json not found for project_id: ${projectId}`);
+            throw error;
+        }
+        return { data: JSON.parse(await fs.readFile(packagePath, 'utf8')) };
+    }
+    const filePath = await resolveInsideRoot(root, args.relative_path);
+    const stat = await fs.stat(filePath);
+    if (!stat.isFile())
+        throw new Error('Resource file path must point to a regular file.');
+    if (stat.size > MAX_PROJECT_FILE_BYTES)
+        throw new Error(`Resource file is too large for text preview: ${stat.size} bytes.`);
+    const buffer = await fs.readFile(filePath);
+    if (looksBinary(buffer))
+        throw new Error('Resource file appears to be binary; text resources only support textual files.');
+    return { text: buffer.toString('utf8') };
+}

package/dist/device/runtime-owner.d.ts

@@ -0,0 +1,41 @@
+import { type DeviceStatePaths } from './device-state.js';
+export type RuntimeMode = 'foreground' | 'windows' | 'systemd' | 'pm2' | 'bootstrap';
+export interface RuntimeOwnerStatus {
+    product: 'MCP Device';
+    mode: RuntimeMode;
+    pid: number;
+    startedAt: number;
+    executable: string;
+    entrypoint: string;
+    deviceId: string | null;
+}
+export declare function probeRuntimeOwner(paths?: DeviceStatePaths, platform?: NodeJS.Platform | string): Promise<RuntimeOwnerStatus | null>;
+export declare class RuntimeOwner {
+    readonly paths: DeviceStatePaths;
+    readonly endpoint: string;
+    readonly mode: RuntimeMode;
+    private readonly platform;
+    private readonly nonce;
+    private readonly status;
+    private server?;
+    private onStop?;
+    constructor({ paths, platform, mode, onStop }: {
+        paths?: DeviceStatePaths;
+        platform?: NodeJS.Platform | string;
+        mode: RuntimeMode;
+        onStop?: () => Promise<void> | void;
+    });
+    acquire(): Promise<void>;
+    bootstrap(): Promise<void>;
+    setDeviceId(deviceId: string): void;
+    release(): Promise<void>;
+}
+export declare function stopRuntimeOwner(paths?: DeviceStatePaths, platform?: NodeJS.Platform | string): Promise<boolean>;
+export declare function acquireRuntimeOwner(owner: RuntimeOwner, { confirmTakeover, waitMs, pollMs }?: {
+    confirmTakeover?: (existing: RuntimeOwnerStatus) => Promise<boolean> | boolean;
+    waitMs?: number;
+    pollMs?: number;
+}): Promise<{
+    takenOver: boolean;
+    previous: RuntimeOwnerStatus | null;
+}>;