@myagentroam/node 0.13.11 → 0.13.12

package/dist/remote-desktop/ultravnc-config.js

@@ -0,0 +1,35 @@
+import { obfuscateVncPassword } from './vnc-password.js';
+/** Writes the Win32 profile representation of UltraVNC's eight-byte password. */
+export function ultraVncProfilePassword(password) {
+    const encoded = obfuscateVncPassword(password);
+    try {
+        const checksum = encoded.reduce((sum, byte) => (sum + byte) & 255, 0);
+        return Buffer.concat([encoded, Buffer.from([checksum])]).toString('hex');
+    }
+    finally {
+        encoded.fill(0);
+    }
+}
+/** Configures an authenticated local-only RFB server without file transfer. */
+export function ultraVncConfig(port, password) {
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new Error('DESKTOP_BACKEND_CONFIG_INVALID');
+    return [
+        '[admin]',
+        'LoopbackOnly=1',
+        'AllowLoopback=1',
+        'AuthRequired=1',
+        'SocketConnect=1',
+        'HTTPConnect=0',
+        'UseIpv6=0',
+        'AutoPortSelect=0',
+        `PortNumber=${port}`,
+        'InputsEnabled=1',
+        'QuerySetting=0',
+        'FileTransferEnabled=0',
+        'secondary=1',
+        '[UltraVNC]',
+        `passwd=${ultraVncProfilePassword(password)}`,
+        ''
+    ].join('\r\n');
+}

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

@@ -0,0 +1,180 @@
+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 { ultraVncConfig } from './ultravnc-config.js';
+/** Owns one UltraVNC process and its authenticated loopback connections. */
+export class UltraVncManagedProcess {
+    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 !== 'win32' || !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-ultravnc-'));
+        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, 'ultravnc.ini');
+            await writeFile(config, ultraVncConfig(port, secret), { flag: 'wx', mode: 0o600 });
+            if (deadline.aborted)
+                throw new RemoteDesktopError('DESKTOP_SETUP_CANCELLED');
+            const child = spawn(options.binaryPath, ['-run', '-multi', '-config', config], {
+                cwd: dirname(options.binaryPath),
+                windowsHide: true,
+                stdio: ['ignore', 'ignore', 'pipe']
+            });
+            backend = new UltraVncManagedProcess(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/vnc-password.js

@@ -0,0 +1,15 @@
+import { createCipheriv } from 'node:crypto';
+/** Standard VNC password-file obfuscation; the result is not a password hash. */
+export function obfuscateVncPassword(password) {
+    if (password.length !== 8 || password.includes(0))
+        throw new Error('DESKTOP_BACKEND_CONFIG_INVALID');
+    const key = Buffer.from('e84ad660c4721ae0'.repeat(3), 'hex');
+    try {
+        const cipher = createCipheriv('des-ede3', key, null);
+        cipher.setAutoPadding(false);
+        return Buffer.concat([cipher.update(password), cipher.final()]);
+    }
+    finally {
+        key.fill(0);
+    }
+}

package/dist/remote-desktop/windows-managed-binaries.js

@@ -0,0 +1,18 @@
+import { access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { join } from 'node:path';
+import { managedBinariesPlatformDirectory } from '../managed-binaries.js';
+/** Discover only the packaged Windows backend, never a system-wide VNC service. */
+export async function windowsManagedDesktopBinaries(packageDirectory, platform = process.platform, architecture = process.arch) {
+    if (platform !== 'win32' || architecture !== 'x64')
+        return undefined;
+    try {
+        const directory = join(packageDirectory ?? managedBinariesPlatformDirectory('win32', 'x64'), 'vendor/ultravnc/win32-x64');
+        for (const name of ['winvnc.exe', 'vnchooks.dll', 'ddengine64.dll', 'ultravnc.portable'])
+            await access(join(directory, name), constants.R_OK);
+        return { binaryPath: join(directory, 'winvnc.exe') };
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -0,0 +1,126 @@
+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 { UltraVncManagedProcess } from './ultravnc-managed-process.js';
+const run = promisify(execFile);
+const SCREEN_QUERY = `
+$ErrorActionPreference = "Stop"
+if (-not [Environment]::UserInteractive) { exit 2 }
+Add-Type -AssemblyName System.Windows.Forms
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new()
+$screens = @([System.Windows.Forms.Screen]::AllScreens | ForEach-Object {
+  @{ name=$_.DeviceName; primary=$_.Primary; x=$_.Bounds.X; y=$_.Bounds.Y;
+     width=$_.Bounds.Width; height=$_.Bounds.Height }
+})
+ConvertTo-Json -InputObject $screens -Compress
+`;
+/** Maps Windows virtual-screen coordinates into the full VNC framebuffer. */
+export function windowsDesktopLayout(screens, generation, revision) {
+    if (!screens.length)
+        throw new RemoteDesktopError('DESKTOP_TOPOLOGY_UNAVAILABLE');
+    const minX = Math.min(...screens.map((screen) => screen.x));
+    const minY = Math.min(...screens.map((screen) => screen.y));
+    const maxX = Math.max(...screens.map((screen) => screen.x + screen.width));
+    const maxY = Math.max(...screens.map((screen) => screen.y + screen.height));
+    const result = remoteDesktopDescriptionSchema.safeParse({
+        desktopGeneration: generation,
+        topologyRevision: revision,
+        framebuffer: { width: maxX - minX, height: maxY - minY },
+        displays: screens.map((screen) => ({
+            displayId: Buffer.from(screen.name, 'utf8').toString('base64url').padEnd(8, '_'),
+            name: screen.name,
+            primary: screen.primary,
+            nativeBounds: { x: screen.x, y: screen.y, width: screen.width, height: screen.height },
+            framebufferBounds: {
+                x: screen.x - minX,
+                y: screen.y - minY,
+                width: screen.width,
+                height: screen.height
+            },
+            nativeToFramebuffer: [1, 0, 0, 1, minX === 0 ? 0 : -minX, minY === 0 ? 0 : -minY]
+        }))
+    });
+    if (!result.success)
+        throw new RemoteDesktopError('DESKTOP_TOPOLOGY_UNAVAILABLE');
+    return result.data;
+}
+async function queryScreens(signal) {
+    const { stdout } = await run('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', SCREEN_QUERY], {
+        windowsHide: true,
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024,
+        signal
+    });
+    return JSON.parse(stdout);
+}
+/** Owns the current interactive Windows GUI layout and one shared UltraVNC backend. */
+export class WindowsRemoteDesktopRuntime {
+    options;
+    #pool;
+    #generation = randomUUID();
+    #layout;
+    #signature = '';
+    #revision = 0;
+    #disposed = false;
+    constructor(options) {
+        this.options = options;
+        this.#pool = new TigerVncBackendPool((signal, onUnexpectedExit) => UltraVncManagedProcess.start({ binaryPath: options.binaryPath, onUnexpectedExit }, signal), () => options.fence('DESKTOP_BACKEND_CLOSED'));
+    }
+    static async start(options, signal) {
+        const runtime = new WindowsRemoteDesktopRuntime(options);
+        await runtime.refresh(signal);
+        return runtime;
+    }
+    async refresh(signal) {
+        const screens = (await queryScreens(signal)).sort((left, right) => left.name.localeCompare(right.name));
+        const signature = JSON.stringify(screens.map((screen) => [
+            screen.name, screen.primary, screen.x, screen.y, screen.width, screen.height
+        ]));
+        if (this.#disposed)
+            throw new RemoteDesktopError('DESKTOP_BACKEND_CLOSED');
+        if (signature === this.#signature)
+            return;
+        const layout = windowsDesktopLayout(screens, 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/x11-desktop-topology.js

@@ -0,0 +1,82 @@
+import { RemoteDesktopError } from './desktop-error.js';
+import { X11TopologySource } from './x11-topology-source.js';
+import { X11Topology } from './x11-topology.js';
+/** Owns one XRandR subscription and synchronously fences users before accepting a new layout. */
+export class X11DesktopTopology {
+    fence;
+    #topology;
+    #source;
+    #stopped = false;
+    #unavailable = false;
+    #stopPromise;
+    constructor(generation, fence) {
+        this.fence = fence;
+        this.#topology = new X11Topology(generation);
+    }
+    static async start(options, signal, startSource = X11TopologySource.start) {
+        const owner = new X11DesktopTopology(options.generation, options.fence);
+        owner.#source = await startSource({
+            binaryPath: options.binaryPath,
+            display: options.display,
+            xAuthority: options.xAuthority,
+            onSnapshot: (snapshot) => {
+                if (!owner.#stopped && !owner.#unavailable)
+                    owner.#topology.accept(snapshot);
+            },
+            onInvalidated: (event) => {
+                if (owner.#stopped || owner.#unavailable)
+                    return;
+                owner.#topology.invalidate(event);
+                owner.fence();
+            },
+            onUnavailable: () => {
+                if (owner.#stopped || owner.#unavailable)
+                    return;
+                owner.#unavailable = true;
+                owner.#topology.unavailable();
+                owner.fence();
+            }
+        }, signal);
+        // A source must not become usable merely because its start promise resolved.
+        try {
+            owner.describe();
+        }
+        catch (error) {
+            await owner.stop();
+            throw error;
+        }
+        return owner;
+    }
+    describe() {
+        if (this.#stopped || this.#unavailable)
+            throw new RemoteDesktopError('DESKTOP_TOPOLOGY_UNAVAILABLE');
+        return this.#topology.describe();
+    }
+    matches(generation, revision, width, height) {
+        try {
+            const layout = this.describe();
+            return (layout.desktopGeneration === generation &&
+                layout.topologyRevision === revision &&
+                layout.framebuffer.width === width &&
+                layout.framebuffer.height === height);
+        }
+        catch {
+            return false;
+        }
+    }
+    stop() {
+        if (this.#stopPromise)
+            return this.#stopPromise;
+        this.#stopped = true;
+        this.#topology.unavailable();
+        this.#stopPromise = (async () => {
+            try {
+                this.fence();
+            }
+            finally {
+                await this.#source?.stop();
+            }
+        })();
+        return this.#stopPromise;
+    }
+}

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

@@ -0,0 +1,99 @@
+import { randomUUID } from 'node:crypto';
+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 { TigerVncManagedProcess } from './tigervnc-managed-process.js';
+import { X11DesktopTopology } from './x11-desktop-topology.js';
+/** Composes one X11 desktop and its Remote-only backend. */
+export class X11RemoteDesktopRuntime {
+    options;
+    #pool;
+    #topology;
+    #disposed = false;
+    constructor(options) {
+        this.options = options;
+        this.#pool = new TigerVncBackendPool((signal, onUnexpectedExit) => TigerVncManagedProcess.start({
+            binaryPath: options.binaryPath,
+            display: options.display,
+            xAuthority: options.xAuthority,
+            onUnexpectedExit
+        }, signal), () => options.fence('DESKTOP_BACKEND_CLOSED'));
+    }
+    static async start(options, signal) {
+        if (!Number.isSafeInteger(options.maxPixels) || options.maxPixels < 1)
+            throw new RemoteDesktopError('DESKTOP_BACKEND_CONFIG_INVALID');
+        const runtime = new X11RemoteDesktopRuntime(options);
+        try {
+            runtime.#topology = await X11DesktopTopology.start({
+                generation: randomUUID(),
+                binaryPath: options.topologyBinary,
+                display: options.display,
+                xAuthority: options.xAuthority,
+                fence: () => options.fence('DESKTOP_TOPOLOGY_UNAVAILABLE')
+            }, signal);
+            return runtime;
+        }
+        catch (error) {
+            await runtime.dispose();
+            throw error;
+        }
+    }
+    describe() {
+        if (this.#disposed || !this.#topology)
+            throw new RemoteDesktopError('DESKTOP_BACKEND_CLOSED');
+        return this.#topology.describe();
+    }
+    isCurrent = (command) => {
+        try {
+            const layout = this.describe();
+            return (this.#pool.isAvailable() &&
+                layout.desktopGeneration === command.desktopGeneration &&
+                layout.topologyRevision === command.topologyRevision);
+        }
+        catch {
+            return false;
+        }
+    };
+    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.#matches(command, width, height),
+        onAttached: callbacks.attached,
+        onFailure: callbacks.failed
+    }));
+    async dispose() {
+        let failure;
+        if (!this.#disposed) {
+            this.#disposed = true;
+            try {
+                this.options.fence('DESKTOP_SESSION_UNAVAILABLE');
+            }
+            catch (error) {
+                failure ??= error;
+            }
+        }
+        try {
+            await this.#topology?.stop();
+        }
+        catch (error) {
+            failure ??= error;
+        }
+        try {
+            await this.#pool.dispose();
+        }
+        catch (error) {
+            failure ??= error;
+        }
+        if (failure !== undefined)
+            throw failure;
+    }
+    #matches(command, width, height) {
+        if (!this.isCurrent(command) || !this.#topology)
+            return false;
+        return this.#topology.matches(command.desktopGeneration, this.#topology.describe().topologyRevision, width, height);
+    }
+}