@myagentroam/node 0.13.11 → 0.13.13

package/dist/remote-desktop/macos-remote-desktop-runtime.js

@@ -0,0 +1,121 @@
+import { execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { promisify } from 'node:util';
+import { remoteDesktopDescriptionSchema } from '@myagentroam/protocol';
+import { RemoteDesktopError } from './desktop-error.js';
+import { PooledDesktopAttachment } from './pooled-desktop-attachment.js';
+import { RemoteDesktopAttachment } from './remote-desktop-attachment.js';
+import { TigerVncBackendPool } from './tigervnc-backend-pool.js';
+import { MacVncManagedProcess } from './macvnc-managed-process.js';
+const run = promisify(execFile);
+/** Maps native display bounds to macVNC pixels without rounding the display scale. */
+export function macosCombinedDesktopLayout(screens, generation, revision) {
+    if (screens.length === 0)
+        throw new RemoteDesktopError('DESKTOP_TOPOLOGY_UNAVAILABLE');
+    const left = Math.min(...screens.map((screen) => screen.x));
+    const top = Math.min(...screens.map((screen) => screen.y));
+    const right = Math.max(...screens.map((screen) => screen.x + screen.width));
+    const bottom = Math.max(...screens.map((screen) => screen.y + screen.height));
+    const scaleX = Math.max(...screens.map((screen) => screen.pixelWidth / screen.width));
+    const scaleY = Math.max(...screens.map((screen) => screen.pixelHeight / screen.height));
+    const result = remoteDesktopDescriptionSchema.safeParse({
+        desktopGeneration: generation,
+        topologyRevision: revision,
+        framebuffer: {
+            width: Math.round((right - left) * scaleX),
+            height: Math.round((bottom - top) * scaleY)
+        },
+        displays: screens.map((screen) => ({
+            displayId: `display_${screen.id}`,
+            name: `Display ${screen.id}`,
+            primary: screen.primary,
+            nativeBounds: { x: screen.x, y: screen.y, width: screen.width, height: screen.height },
+            framebufferBounds: {
+                x: Math.round((screen.x - left) * scaleX),
+                y: Math.round((screen.y - top) * scaleY),
+                width: Math.round((screen.x + screen.width - left) * scaleX) -
+                    Math.round((screen.x - left) * scaleX),
+                height: Math.round((screen.y + screen.height - top) * scaleY) -
+                    Math.round((screen.y - top) * scaleY)
+            },
+            nativeToFramebuffer: [scaleX, 0, 0, scaleY, -left * scaleX || 0, -top * scaleY || 0]
+        }))
+    });
+    if (!result.success)
+        throw new RemoteDesktopError('DESKTOP_TOPOLOGY_UNAVAILABLE');
+    return result.data;
+}
+async function queryScreens(binary, signal) {
+    const { stdout } = await run(binary, [], { encoding: 'utf8', maxBuffer: 64 * 1024, signal });
+    const parsed = JSON.parse(stdout);
+    if (!parsed ||
+        typeof parsed !== 'object' ||
+        !('displays' in parsed) ||
+        !Array.isArray(parsed.displays))
+        throw new RemoteDesktopError('DESKTOP_TOPOLOGY_UNAVAILABLE');
+    return parsed.displays;
+}
+/** Owns the current interactive macOS desktop layout and one shared macVNC backend. */
+export class MacosRemoteDesktopRuntime {
+    options;
+    #pool;
+    #generation = randomUUID();
+    #layout;
+    #signature = '';
+    #revision = 0;
+    #disposed = false;
+    constructor(options) {
+        this.options = options;
+        this.#pool = new TigerVncBackendPool((signal, onUnexpectedExit) => MacVncManagedProcess.start({ binaryPath: options.binaryPath, onUnexpectedExit }, signal), () => options.fence('DESKTOP_BACKEND_CLOSED'));
+    }
+    static async start(options, signal) {
+        const runtime = new MacosRemoteDesktopRuntime(options);
+        await runtime.refresh(signal);
+        return runtime;
+    }
+    async refresh(signal) {
+        const screens = (await queryScreens(this.options.topologyBinary, signal)).sort((left, right) => left.id - right.id);
+        const signature = JSON.stringify(screens);
+        if (this.#disposed)
+            throw new RemoteDesktopError('DESKTOP_BACKEND_CLOSED');
+        if (signature === this.#signature)
+            return;
+        const layout = macosCombinedDesktopLayout(screens.filter((screen) => screen.primary), this.#generation, this.#revision + 1);
+        if (layout.framebuffer.width * layout.framebuffer.height > this.options.maxPixels)
+            throw new RemoteDesktopError('DESKTOP_TOPOLOGY_UNAVAILABLE');
+        if (this.#layout)
+            this.options.fence('DESKTOP_TOPOLOGY_UNAVAILABLE');
+        this.#signature = signature;
+        this.#revision++;
+        this.#layout = layout;
+    }
+    describe() {
+        if (this.#disposed || !this.#layout || !this.#pool.isAvailable())
+            throw new RemoteDesktopError('DESKTOP_BACKEND_CLOSED');
+        return structuredClone(this.#layout);
+    }
+    isCurrent = (command) => !this.#disposed &&
+        this.#pool.isAvailable() &&
+        !!this.#layout &&
+        this.#layout.desktopGeneration === command.desktopGeneration &&
+        this.#layout.topologyRevision === command.topologyRevision;
+    createAttachment = (command, frontend, callbacks) => new PooledDesktopAttachment(this.#pool, frontend, (backend) => new RemoteDesktopAttachment({
+        attachmentId: command.attachmentId,
+        frontend,
+        backend,
+        mode: command.mode,
+        maxPixels: this.options.maxPixels,
+        isCurrentTopology: (width, height) => this.isCurrent(command) &&
+            this.#layout?.framebuffer.width === width &&
+            this.#layout.framebuffer.height === height,
+        onAttached: callbacks.attached,
+        onFailure: callbacks.failed
+    }));
+    async dispose() {
+        if (!this.#disposed) {
+            this.#disposed = true;
+            this.options.fence('DESKTOP_SESSION_UNAVAILABLE');
+        }
+        await this.#pool.dispose();
+    }
+}

package/dist/remote-desktop/macvnc-managed-process.js

@@ -0,0 +1,196 @@
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { connect, createServer } from 'node:net';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { RemoteDesktopError } from './desktop-error.js';
+import { handshakeRfbBackend } from './rfb-backend-handshake.js';
+import { obfuscateVncPassword } from './vnc-password.js';
+/** Owns one macVNC process and its authenticated loopback connections. */
+export class MacVncManagedProcess {
+    child;
+    directory;
+    port;
+    secret;
+    onUnexpectedExit;
+    #connections = new Set();
+    #exited;
+    #stopping = false;
+    #ready = false;
+    #didExit = false;
+    #stopPromise;
+    constructor(child, directory, port, secret, onUnexpectedExit) {
+        this.child = child;
+        this.directory = directory;
+        this.port = port;
+        this.secret = secret;
+        this.onUnexpectedExit = onUnexpectedExit;
+        child.on('error', () => { });
+        child.stderr?.resume();
+        this.#exited = new Promise((resolve) => {
+            child.once('close', () => {
+                this.#didExit = true;
+                if (this.#ready && !this.#stopping) {
+                    try {
+                        this.onUnexpectedExit();
+                    }
+                    catch {
+                        // A notification failure must not prevent process cleanup.
+                    }
+                }
+                resolve();
+            });
+        });
+    }
+    static async start(options, signal) {
+        if (process.platform !== 'darwin' || !isAbsolute(options.binaryPath))
+            throw new RemoteDesktopError('DESKTOP_BACKEND_CONFIG_INVALID');
+        const deadline = AbortSignal.any([signal, AbortSignal.timeout(10_000)]);
+        if (deadline.aborted)
+            throw new RemoteDesktopError('DESKTOP_SETUP_CANCELLED');
+        const directory = await mkdtemp(join(tmpdir(), 'mar-macvnc-'));
+        const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+        const secret = randomBytes(8);
+        for (let i = 0; i < secret.length; i++)
+            secret[i] = alphabet.charCodeAt(secret[i] & 63);
+        let backend;
+        try {
+            const port = await availableLoopbackPort();
+            if (deadline.aborted)
+                throw new RemoteDesktopError('DESKTOP_SETUP_CANCELLED');
+            const config = join(directory, 'vnc-password');
+            const encoded = obfuscateVncPassword(secret);
+            try {
+                await writeFile(config, encoded, { flag: 'wx', mode: 0o600 });
+            }
+            finally {
+                encoded.fill(0);
+            }
+            if (deadline.aborted)
+                throw new RemoteDesktopError('DESKTOP_SETUP_CANCELLED');
+            const child = spawn(options.binaryPath, [
+                '-rfbport',
+                String(port),
+                '-rfbportv6',
+                '0',
+                '-listen',
+                '127.0.0.1',
+                '-rfbauth',
+                config,
+                '-alwaysshared'
+            ], {
+                cwd: dirname(options.binaryPath),
+                windowsHide: true,
+                stdio: ['ignore', 'ignore', 'pipe']
+            });
+            backend = new MacVncManagedProcess(child, directory, port, secret, options.onUnexpectedExit);
+            while (!deadline.aborted && !backend.#didExit) {
+                try {
+                    const connection = await backend.connect(64 * 1024 * 1024, deadline);
+                    connection.socket.destroy();
+                    if (backend.#didExit || deadline.aborted)
+                        throw new RemoteDesktopError('DESKTOP_BACKEND_CLOSED');
+                    backend.#ready = true;
+                    return backend;
+                }
+                catch (error) {
+                    if (deadline.aborted || backend.#didExit)
+                        throw error;
+                    await delay(50, undefined, { signal: deadline });
+                }
+            }
+            throw new RemoteDesktopError('DESKTOP_BACKEND_START_FAILED');
+        }
+        catch (error) {
+            if (backend)
+                await backend.stop();
+            else {
+                secret.fill(0);
+                await rm(directory, { recursive: true, force: true });
+            }
+            if (deadline.aborted)
+                throw new RemoteDesktopError('DESKTOP_SETUP_CANCELLED');
+            if (error instanceof RemoteDesktopError)
+                throw error;
+            throw new RemoteDesktopError('DESKTOP_BACKEND_START_FAILED');
+        }
+    }
+    async connect(maxPixels, signal) {
+        if (this.#stopping || this.#didExit)
+            throw new RemoteDesktopError('DESKTOP_BACKEND_CLOSED');
+        const socket = connect({ host: '127.0.0.1', port: this.port });
+        this.#connections.add(socket);
+        socket.once('close', () => this.#connections.delete(socket));
+        try {
+            await new Promise((resolve, reject) => {
+                const cleanup = () => {
+                    socket.off('connect', connected);
+                    socket.off('error', failed);
+                    signal.removeEventListener('abort', aborted);
+                };
+                const connected = () => {
+                    cleanup();
+                    resolve();
+                };
+                const failed = () => {
+                    cleanup();
+                    reject(new RemoteDesktopError('DESKTOP_BACKEND_CLOSED'));
+                };
+                const aborted = () => {
+                    cleanup();
+                    reject(new RemoteDesktopError('DESKTOP_SETUP_CANCELLED'));
+                };
+                socket.once('connect', connected);
+                socket.once('error', failed);
+                if (signal.aborted)
+                    aborted();
+                else
+                    signal.addEventListener('abort', aborted, { once: true });
+            });
+            const init = await handshakeRfbBackend(socket, this.secret, maxPixels, signal);
+            return { socket, init };
+        }
+        catch (error) {
+            socket.on('error', () => { });
+            socket.destroy();
+            throw error;
+        }
+    }
+    stop() {
+        if (this.#stopPromise)
+            return this.#stopPromise;
+        this.#stopping = true;
+        this.#stopPromise = (async () => {
+            for (const socket of this.#connections)
+                socket.destroy();
+            if (!this.#didExit)
+                this.child.kill();
+            const exited = await Promise.race([
+                this.#exited.then(() => true),
+                delay(5_000, undefined, { ref: false }).then(() => false)
+            ]);
+            if (!exited)
+                throw new RemoteDesktopError('DESKTOP_BACKEND_CLOSED');
+            this.secret.fill(0);
+            await rm(this.directory, { recursive: true, force: true });
+        })().catch((error) => {
+            this.#stopPromise = undefined;
+            throw error;
+        });
+        return this.#stopPromise;
+    }
+}
+async function availableLoopbackPort() {
+    const listener = createServer();
+    return new Promise((resolve, reject) => {
+        listener.once('error', reject);
+        listener.listen(0, '127.0.0.1', () => {
+            const address = listener.address();
+            if (!address || typeof address === 'string')
+                return listener.close(() => reject(new Error('port')));
+            listener.close((error) => (error ? reject(error) : resolve(address.port)));
+        });
+    });
+}

package/dist/remote-desktop/pooled-desktop-attachment.js

@@ -0,0 +1,62 @@
+import { RemoteDesktopError } from './desktop-error.js';
+/** Acquires a Remote-owned backend after OPEN and releases it after connection cleanup. */
+export class PooledDesktopAttachment {
+    pool;
+    frontend;
+    create;
+    #cancel = new AbortController();
+    #reference;
+    #attachment;
+    #opening;
+    #closing;
+    #closed = false;
+    #started = false;
+    constructor(pool, frontend, create) {
+        this.pool = pool;
+        this.frontend = frontend;
+        this.create = create;
+    }
+    open(signal) {
+        if (this.#started || this.#closed)
+            return Promise.reject(new RemoteDesktopError('DESKTOP_RFB_CLOSED'));
+        this.#started = true;
+        const deadline = AbortSignal.any([signal, this.#cancel.signal]);
+        this.#opening = (async () => {
+            this.#reference = await this.pool.acquire(deadline);
+            if (deadline.aborted)
+                throw new RemoteDesktopError('DESKTOP_SETUP_CANCELLED');
+            this.#attachment = this.create(this.#reference.backend);
+            await this.#attachment.open(deadline);
+        })();
+        return this.#opening;
+    }
+    close(signal) {
+        if (this.#closed)
+            return Promise.resolve();
+        if (this.#closing)
+            return this.#closing;
+        this.#cancel.abort();
+        // Fence synchronously, even if startup or native cleanup is still pending.
+        const closing = this.#attachment?.close(signal).then(() => ({ ok: true }), (error) => ({ ok: false, error }));
+        if (!this.#attachment)
+            this.frontend.destroy();
+        this.#closing = (async () => {
+            await this.#opening?.catch(() => { });
+            if (closing) {
+                const result = await closing;
+                if (!result.ok)
+                    throw result.error;
+            }
+            else if (this.#attachment)
+                await this.#attachment.close(signal);
+            if (this.#reference)
+                await this.#reference.release();
+            this.#reference = undefined;
+            this.#attachment = undefined;
+            this.#closed = true;
+        })().finally(() => {
+            this.#closing = undefined;
+        });
+        return this.#closing;
+    }
+}

package/dist/remote-desktop/relay-desktop-service.js

@@ -0,0 +1,40 @@
+import { RemoteDesktopError } from './desktop-error.js';
+import { DesktopServiceCore } from './desktop-service-core.js';
+/** Binds one Server-authenticated relay socket to the shared attachment lifecycle. */
+export class RelayDesktopService extends DesktopServiceCore {
+    constructor(options) {
+        super({
+            path: 'relay',
+            ...(options.registry === undefined ? {} : { registry: options.registry }),
+            nodeGeneration: options.nodeGeneration,
+            ...(options.now === undefined ? {} : { now: options.now }),
+            isCurrent: (command) => command.type === 'desktop.relay.prepare' &&
+                command.nodeGeneration === options.nodeGeneration() &&
+                options.isCurrent(command),
+            createAttachment: (command, stream, callbacks) => {
+                if (command.type !== 'desktop.relay.prepare')
+                    throw new RemoteDesktopError('DESKTOP_TRANSPORT_ERROR');
+                return options.createAttachment(command, stream, callbacks);
+            },
+            emit: (event) => options.emit(event),
+            transport: (command) => {
+                if (command.type !== 'desktop.relay.prepare')
+                    return undefined;
+                const channel = options.connect();
+                return {
+                    channel,
+                    valid: () => channel.readyState === 0 || channel.readyState === 1,
+                    maxMessageBytes: () => 16_384,
+                    start: () => channel.send(JSON.stringify({
+                        type: 'desktop.relay.node',
+                        nodeId: options.nodeId,
+                        nodeGeneration: command.nodeGeneration,
+                        attachmentId: command.attachmentId,
+                        ticket: command.ticket,
+                        credential: options.credential()
+                    }))
+                };
+            }
+        });
+    }
+}

package/dist/remote-desktop/remote-desktop-attachment.js

@@ -0,0 +1,87 @@
+import { RemoteDesktopError } from './desktop-error.js';
+import { TigerVncRfbSession, TigerVncSetupCleanupError } from './tigervnc-rfb-session.js';
+/** Owns one Remote attachment and its cleanup, never the shared backend. */
+export class RemoteDesktopAttachment {
+    options;
+    #state = 'new';
+    #session;
+    #pendingCleanup;
+    #opening;
+    #closing;
+    #closeRequested = false;
+    #cancel = new AbortController();
+    constructor(options) {
+        this.options = options;
+        if (!options.attachmentId)
+            throw new RemoteDesktopError('DESKTOP_BACKEND_CONFIG_INVALID');
+    }
+    open(signal) {
+        if (this.#state !== 'new')
+            return Promise.reject(new RemoteDesktopError('DESKTOP_RFB_CLOSED'));
+        if (signal.aborted)
+            return Promise.reject(new RemoteDesktopError('DESKTOP_SETUP_CANCELLED'));
+        this.#state = 'opening';
+        this.#opening = this.#start(AbortSignal.any([signal, this.#cancel.signal]));
+        return this.#opening;
+    }
+    close(signal) {
+        if (this.#state === 'closed')
+            return Promise.resolve();
+        if (this.#closing)
+            return this.#closing;
+        this.#closeRequested = true;
+        this.#state = 'cleanup';
+        this.#cancel.abort();
+        if (this.#session)
+            this.#session.fence();
+        else
+            this.options.frontend.destroy();
+        this.#closing = (async () => {
+            await this.#opening?.catch(() => { });
+            await this.#finishCleanup(signal);
+            this.#state = 'closed';
+        })().finally(() => {
+            this.#closing = undefined;
+        });
+        return this.#closing;
+    }
+    async #start(signal) {
+        try {
+            this.#session = await TigerVncRfbSession.open({
+                ...this.options,
+                isControlOwner: () => !this.#closeRequested,
+                onFailure: (code) => {
+                    void this.close(AbortSignal.timeout(5_000)).catch(() => { });
+                    this.options.onFailure(code);
+                }
+            }, signal);
+            if (this.#closeRequested || signal.aborted)
+                throw new RemoteDesktopError('DESKTOP_SETUP_CANCELLED');
+            this.#state = 'active';
+        }
+        catch (error) {
+            if (error instanceof TigerVncSetupCleanupError) {
+                this.#pendingCleanup = error;
+                this.#state = 'cleanup';
+                throw error;
+            }
+            try {
+                await this.#finishCleanup(AbortSignal.timeout(5_000));
+                this.#state = 'closed';
+            }
+            catch (cleanupError) {
+                this.#state = 'cleanup';
+                throw cleanupError;
+            }
+            throw error;
+        }
+    }
+    async #finishCleanup(signal) {
+        if (this.#session)
+            await this.#session.close(signal);
+        if (this.#pendingCleanup)
+            await this.#pendingCleanup.retryCleanup(signal);
+        this.#session = undefined;
+        this.#pendingCleanup = undefined;
+    }
+}

package/dist/remote-desktop/rfb-backend-handshake.js

@@ -0,0 +1,98 @@
+import { RemoteDesktopError } from './desktop-error.js';
+import { RfbHandshakeIo } from './rfb-handshake-io.js';
+import { createCipheriv } from 'node:crypto';
+/**
+ * Temporarily owns a backend stream during RFB 3.8 setup. The caller supplies
+ * the setup deadline and, on success, resumes ownership of the paused stream.
+ * It never exposes backend credentials or accepts an unauthenticated backend.
+ */
+export async function handshakeRfbBackend(stream, password, maxPixels, signal) {
+    const io = new RfbHandshakeIo(stream, signal);
+    try {
+        if (password.length < 1 ||
+            password.length > 8 ||
+            password.includes(0) ||
+            !Number.isSafeInteger(maxPixels) ||
+            maxPixels < 1)
+            throw new RemoteDesktopError('DESKTOP_RFB_INVALID');
+        if (!(await io.read(12)).equals(Buffer.from('RFB 003.008\n')))
+            throw new RemoteDesktopError('DESKTOP_RFB_INVALID');
+        await io.write(Buffer.from('RFB 003.008\n'));
+        const securityCount = (await io.read(1))[0];
+        if (securityCount === 0 || !(await io.read(securityCount)).includes(2))
+            throw new RemoteDesktopError('DESKTOP_BACKEND_AUTH_UNAVAILABLE');
+        await io.write(Buffer.from([2]));
+        const challenge = await io.read(16);
+        const response = vncResponse(challenge, password);
+        try {
+            await io.write(response);
+        }
+        finally {
+            response.fill(0);
+            challenge.fill(0);
+        }
+        if ((await io.read(4)).readUInt32BE() !== 0)
+            throw new RemoteDesktopError('DESKTOP_BACKEND_AUTH_FAILED');
+        // Every attachment is shared, regardless of any frontend request.
+        await io.write(Buffer.from([1]));
+        const header = await io.read(24);
+        const width = header.readUInt16BE(0);
+        const height = header.readUInt16BE(2);
+        const nameLength = header.readUInt32BE(20);
+        if (width === 0 ||
+            height === 0 ||
+            width * height > maxPixels ||
+            nameLength > 4096 ||
+            !validPixelFormat(header.subarray(4, 20)))
+            throw new RemoteDesktopError('DESKTOP_RFB_INVALID');
+        const name = await io.read(nameLength);
+        return { width, height, serverInit: Buffer.concat([header, name]) };
+    }
+    catch (error) {
+        stream.destroy();
+        if (error instanceof RemoteDesktopError)
+            throw error;
+        throw new RemoteDesktopError('DESKTOP_TRANSPORT_ERROR');
+    }
+    finally {
+        io.dispose();
+    }
+}
+function vncResponse(challenge, password) {
+    const key = Buffer.alloc(8);
+    for (let i = 0; i < password.length; i++) {
+        let byte = password[i];
+        byte = ((byte & 0x55) << 1) | ((byte >>> 1) & 0x55);
+        byte = ((byte & 0x33) << 2) | ((byte >>> 2) & 0x33);
+        key[i] = ((byte & 0x0f) << 4) | (byte >>> 4);
+    }
+    // EDE with three identical keys is DES ECB without relying on legacy OpenSSL providers.
+    const expanded = Buffer.concat([key, key, key]);
+    try {
+        const cipher = createCipheriv('des-ede3', expanded, null);
+        cipher.setAutoPadding(false);
+        return Buffer.concat([cipher.update(challenge), cipher.final()]);
+    }
+    finally {
+        key.fill(0);
+        expanded.fill(0);
+    }
+}
+function validPixelFormat(format) {
+    const bpp = format[0];
+    const depth = format[1];
+    if (![8, 16, 32].includes(bpp) || depth === 0 || depth > bpp || format[3] === 0)
+        return false;
+    let occupied = 0n;
+    for (let i = 0; i < 3; i++) {
+        const max = format.readUInt16BE(4 + i * 2);
+        const shift = format[10 + i];
+        if (max === 0 || (max & (max + 1)) !== 0)
+            return false;
+        const mask = BigInt(max) << BigInt(shift);
+        if (mask >= 1n << BigInt(bpp) || (mask & occupied) !== 0n)
+            return false;
+        occupied |= mask;
+    }
+    return true;
+}