@myagentroam/node 0.13.10 → 0.13.12

package/dist/remote-desktop/rfb-client-gate.js

@@ -0,0 +1,318 @@
+var _a;
+import { RemoteDesktopError } from './desktop-error.js';
+/**
+ * Frames and admits client-to-backend RFB messages for one attachment after
+ * both handshakes. It owns neither socket nor lease; the session owner fences,
+ * waits for stream drain, then makes a best-effort standard RFB release.
+ */
+export class RfbClientGate {
+    target;
+    mode;
+    isControlOwner;
+    onFailure;
+    static maxClipboardBytes = 1024 * 1024;
+    static maxEncodings = 256;
+    static maxPressedKeys = 256;
+    static maxQueuedFrames = 1024;
+    static maxFrameBytes = this.maxClipboardBytes + 8;
+    #buffer = Buffer.allocUnsafe(_a.maxFrameBytes);
+    #queue = [];
+    #keys = new Set();
+    #begin = 0;
+    #end = 0;
+    #queuedBytes = 0;
+    #buttons = 0;
+    #pointerX = 0;
+    #pointerY = 0;
+    #waitingDrain = false;
+    #inFlight = 0;
+    #inFlightBytes = 0;
+    #extendedClipboard = false;
+    #state = 'active';
+    #transportFailed = false;
+    #fencePromise;
+    #fenceResolve;
+    #fenceReject;
+    constructor(target, mode, isControlOwner, onFailure) {
+        this.target = target;
+        this.mode = mode;
+        this.isControlOwner = isControlOwner;
+        this.onFailure = onFailure;
+        target.on('drain', this.#drain);
+        target.on('error', this.#streamError);
+        target.on('close', this.#streamError);
+    }
+    receive(data) {
+        if (this.#state !== 'active')
+            return;
+        let offset = 0;
+        while (offset < data.byteLength && this.#state === 'active') {
+            if (this.#end === this.#buffer.length && this.#begin > 0) {
+                this.#buffer.copyWithin(0, this.#begin, this.#end);
+                this.#end -= this.#begin;
+                this.#begin = 0;
+            }
+            const count = Math.min(data.byteLength - offset, this.#buffer.length - this.#end);
+            if (count === 0) {
+                this.#fail('DESKTOP_RFB_INVALID');
+                return;
+            }
+            this.#buffer.set(data.subarray(offset, offset + count), this.#end);
+            this.#end += count;
+            offset += count;
+            this.#parse();
+        }
+    }
+    /** Fencing discards unwritten messages; write completion is not an OS input ACK. */
+    fence() {
+        if (this.#fencePromise !== undefined)
+            return this.#fencePromise;
+        if (this.#transportFailed)
+            return Promise.reject(new RemoteDesktopError('DESKTOP_RFB_CLOSED'));
+        if (this.#state === 'active')
+            this.#state = 'fenced';
+        this.#queue.length = 0;
+        this.#queuedBytes = 0;
+        this.#begin = this.#end = 0;
+        this.#fencePromise =
+            (this.#state === 'fenced' && this.#waitingDrain) || this.#inFlight > 0
+                ? new Promise((resolve, reject) => {
+                    this.#fenceResolve = resolve;
+                    this.#fenceReject = reject;
+                })
+                : Promise.resolve(this.#snapshot());
+        return this.#fencePromise;
+    }
+    /** Available after failure for cleanup; it does not confirm delivery or release. */
+    submittedInputSnapshot() {
+        return this.#snapshot();
+    }
+    dispose() {
+        this.#state = 'failed';
+        this.#transportFailed = true;
+        this.#queue.length = 0;
+        this.#queuedBytes = 0;
+        this.target.removeListener('drain', this.#drain);
+        this.target.removeListener('error', this.#streamError);
+        this.target.removeListener('close', this.#streamError);
+        this.#fenceReject?.(new RemoteDesktopError('DESKTOP_RFB_CLOSED'));
+        this.#fenceResolve = this.#fenceReject = undefined;
+    }
+    #parse() {
+        while (this.#begin < this.#end && this.#state === 'active') {
+            const length = this.#frameLength();
+            if (length === undefined || this.#state !== 'active')
+                return;
+            if (this.#end - this.#begin < length)
+                return;
+            let bytes = Buffer.from(this.#buffer.subarray(this.#begin, this.#begin + length));
+            this.#begin += length;
+            if (this.#begin === this.#end)
+                this.#begin = this.#end = 0;
+            const input = bytes[0] === 4 || bytes[0] === 5 || bytes[0] === 6;
+            if (input && this.mode === 'VIEW') {
+                this.#fail('DESKTOP_INPUT_DENIED');
+                return;
+            }
+            if (bytes[0] === 4 && bytes[1] > 1) {
+                this.#fail('DESKTOP_RFB_INVALID');
+                return;
+            }
+            if (bytes[0] === 2) {
+                bytes = this.#filterEncodings(bytes);
+                this.#extendedClipboard = this.mode === 'CONTROL' && this.#hasExtendedClipboard(bytes);
+            }
+            if (bytes[0] === 6 && !this.#validClipboard(bytes)) {
+                this.#fail('DESKTOP_RFB_INVALID');
+                return;
+            }
+            if (this.#queue.length >= _a.maxQueuedFrames ||
+                this.#queuedBytes + bytes.length > _a.maxFrameBytes) {
+                this.#fail('DESKTOP_BACKPRESSURE');
+                return;
+            }
+            this.#queue.push({ bytes, input });
+            this.#queuedBytes += bytes.length;
+            this.#pump();
+        }
+    }
+    #frameLength() {
+        const available = this.#end - this.#begin;
+        const type = this.#buffer[this.#begin];
+        switch (type) {
+            case 0:
+                return 20;
+            case 2: {
+                if (available < 4)
+                    return undefined;
+                const count = this.#buffer.readUInt16BE(this.#begin + 2);
+                if (count > _a.maxEncodings) {
+                    this.#fail('DESKTOP_RFB_INVALID');
+                    return undefined;
+                }
+                return 4 + count * 4;
+            }
+            case 3:
+                return 10;
+            case 4:
+                return 8;
+            case 5:
+                return 6;
+            case 6: {
+                if (available < 8)
+                    return undefined;
+                const declared = this.#buffer.readInt32BE(this.#begin + 4);
+                const length = Math.abs(declared);
+                if (length > _a.maxClipboardBytes) {
+                    this.#fail('DESKTOP_RFB_INVALID');
+                    return undefined;
+                }
+                return 8 + length;
+            }
+            default:
+                this.#fail('DESKTOP_RFB_INVALID');
+                return undefined;
+        }
+    }
+    #filterEncodings(frame) {
+        const allowed = [];
+        for (let offset = 4; offset < frame.length; offset += 4) {
+            const encoding = frame.readInt32BE(offset);
+            if ([0, 1, 2, 5, 7, 16, 21, -223, -224, -239, -308].includes(encoding) ||
+                (encoding >= -32 && encoding <= -23) ||
+                (encoding >= -256 && encoding <= -247) ||
+                (this.mode === 'CONTROL' && encoding === -1063131698))
+                allowed.push(encoding);
+        }
+        const filtered = Buffer.allocUnsafe(4 + allowed.length * 4);
+        filtered[0] = 2;
+        filtered[1] = 0;
+        filtered.writeUInt16BE(allowed.length, 2);
+        allowed.forEach((encoding, index) => filtered.writeInt32BE(encoding, 4 + index * 4));
+        return filtered;
+    }
+    #hasExtendedClipboard(frame) {
+        for (let offset = 4; offset < frame.length; offset += 4) {
+            if (frame.readInt32BE(offset) === -1063131698)
+                return true;
+        }
+        return false;
+    }
+    #validClipboard(frame) {
+        if (frame.readInt32BE(4) >= 0)
+            return true;
+        if (!this.#extendedClipboard || frame.length < 12)
+            return false;
+        const flags = frame.readUInt32BE(8);
+        const formats = flags & 0xffff;
+        const actions = flags & 0xff000000;
+        if ((flags & 0x00ff0000) !== 0 || (formats & ~1) !== 0)
+            return false;
+        if ((actions & 0x01000000) !== 0) {
+            return (actions & ~0x1b000000) === 0 && frame.length === 12 + (formats === 1 ? 4 : 0);
+        }
+        if (actions === 0x08000000)
+            return frame.length === 12;
+        return actions === 0x10000000 && formats === 1 && frame.length > 12;
+    }
+    #pump() {
+        while (this.#state === 'active' && !this.#waitingDrain && this.#queue.length > 0) {
+            const next = this.#queue[0];
+            if (this.#inFlight >= _a.maxQueuedFrames ||
+                this.#inFlightBytes + next.bytes.length > _a.maxFrameBytes)
+                return;
+            const frame = this.#queue.shift();
+            this.#queuedBytes -= frame.bytes.length;
+            if (frame.input) {
+                let ownsControl = false;
+                try {
+                    ownsControl = this.isControlOwner();
+                }
+                catch {
+                    // An unavailable authority is not evidence of ownership.
+                }
+                if (!ownsControl) {
+                    this.#fail('DESKTOP_CONTROL_LOST');
+                    return;
+                }
+            }
+            if (frame.bytes[0] === 4 &&
+                frame.bytes[1] === 1 &&
+                !this.#keys.has(frame.bytes.readUInt32BE(4)) &&
+                this.#keys.size >= _a.maxPressedKeys) {
+                this.#fail('DESKTOP_RFB_INVALID');
+                return;
+            }
+            try {
+                this.#inFlight++;
+                this.#inFlightBytes += frame.bytes.length;
+                const accepted = this.target.write(frame.bytes, (error) => {
+                    this.#inFlight--;
+                    this.#inFlightBytes -= frame.bytes.length;
+                    if (error)
+                        this.#fail('DESKTOP_TRANSPORT_ERROR');
+                    else if (this.#state !== 'active')
+                        this.#finishFence();
+                    else
+                        this.#pump();
+                });
+                this.#recordInput(frame.bytes);
+                this.#waitingDrain = !accepted;
+            }
+            catch {
+                this.#inFlight--;
+                this.#inFlightBytes -= frame.bytes.length;
+                this.#fail('DESKTOP_TRANSPORT_ERROR');
+            }
+        }
+    }
+    #recordInput(frame) {
+        if (frame[0] === 4) {
+            const key = frame.readUInt32BE(4);
+            if (frame[1] !== 0)
+                this.#keys.add(key);
+            else
+                this.#keys.delete(key);
+        }
+        else if (frame[0] === 5) {
+            this.#buttons = frame[1];
+            this.#pointerX = frame.readUInt16BE(2);
+            this.#pointerY = frame.readUInt16BE(4);
+        }
+    }
+    #snapshot() {
+        return { keys: [...this.#keys], buttons: this.#buttons, x: this.#pointerX, y: this.#pointerY };
+    }
+    #drain = () => {
+        this.#waitingDrain = false;
+        if (this.#state !== 'active')
+            this.#finishFence();
+        else
+            this.#pump();
+    };
+    #finishFence() {
+        if (this.#state !== 'active' &&
+            !this.#transportFailed &&
+            (this.#state === 'failed' || !this.#waitingDrain) &&
+            this.#inFlight === 0) {
+            this.#fenceResolve?.(this.#snapshot());
+            this.#fenceResolve = this.#fenceReject = undefined;
+        }
+    }
+    #streamError = () => this.#fail('DESKTOP_TRANSPORT_ERROR');
+    #fail(code) {
+        if (code === 'DESKTOP_TRANSPORT_ERROR') {
+            this.#transportFailed = true;
+            this.#fenceReject?.(new RemoteDesktopError(code));
+            this.#fenceResolve = this.#fenceReject = undefined;
+        }
+        if (this.#state === 'failed')
+            return;
+        this.#state = 'failed';
+        this.#queue.length = 0;
+        this.#queuedBytes = 0;
+        this.#finishFence();
+        this.onFailure(code);
+    }
+}
+_a = RfbClientGate;

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

@@ -0,0 +1,38 @@
+import { RemoteDesktopError } from './desktop-error.js';
+import { RfbHandshakeIo } from './rfb-handshake-io.js';
+/**
+ * Negotiates RFB 3.8 on an already authorized attachment. None is only the
+ * inner RFB security type: this function must never admit an unauthenticated
+ * transport. On success the caller regains the paused stream, including any
+ * buffered client messages, and must pass them through the input gate.
+ */
+export async function handshakeRfbFrontend(stream, serverInit, signal) {
+    const io = new RfbHandshakeIo(stream, signal);
+    try {
+        if (serverInit.length < 24 ||
+            serverInit.length > 24 + 4096 ||
+            serverInit.readUInt32BE(20) !== serverInit.length - 24)
+            throw new RemoteDesktopError('DESKTOP_RFB_INVALID');
+        const banner = Buffer.from('RFB 003.008\n');
+        await io.write(banner);
+        if (!(await io.read(12)).equals(banner))
+            throw new RemoteDesktopError('DESKTOP_RFB_INVALID');
+        await io.write(Buffer.from([1, 1]));
+        if ((await io.read(1))[0] !== 1)
+            throw new RemoteDesktopError('DESKTOP_RFB_INVALID');
+        await io.write(Buffer.alloc(4));
+        // Never let an exclusive browser connection disconnect other observers.
+        if ((await io.read(1))[0] !== 1)
+            throw new RemoteDesktopError('DESKTOP_RFB_INVALID');
+        await io.write(serverInit);
+    }
+    catch (error) {
+        stream.destroy();
+        if (error instanceof RemoteDesktopError)
+            throw error;
+        throw new RemoteDesktopError('DESKTOP_TRANSPORT_ERROR');
+    }
+    finally {
+        io.dispose();
+    }
+}

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

@@ -0,0 +1,91 @@
+import { RemoteDesktopError } from './desktop-error.js';
+/** Temporarily owns paused stream reads and bounded setup writes; it does not own the stream. */
+export class RfbHandshakeIo {
+    stream;
+    signal;
+    #error;
+    #pending;
+    constructor(stream, signal) {
+        this.stream = stream;
+        this.signal = signal;
+        stream.pause();
+        stream.on('error', this.#failed);
+        stream.on('close', this.#closed);
+        stream.on('end', this.#closed);
+        signal.addEventListener('abort', this.#aborted);
+        if (signal.aborted)
+            this.#aborted();
+    }
+    async read(size) {
+        if (size === 0)
+            return Buffer.alloc(0);
+        while (true) {
+            this.#check();
+            const value = this.stream.read(size);
+            if (value !== null) {
+                if (!Buffer.isBuffer(value) || value.length !== size)
+                    throw new RemoteDesktopError('DESKTOP_RFB_INVALID');
+                return value;
+            }
+            await new Promise((resolve, reject) => {
+                const readable = () => finish();
+                const finish = (error) => {
+                    this.stream.off('readable', readable);
+                    this.#pending = undefined;
+                    if (error)
+                        reject(error);
+                    else
+                        resolve();
+                };
+                this.#pending = finish;
+                this.stream.once('readable', readable);
+            });
+        }
+    }
+    async write(value) {
+        this.#check();
+        await new Promise((resolve, reject) => {
+            const finish = (error) => {
+                if (this.#pending !== finish)
+                    return;
+                this.#pending = undefined;
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            };
+            this.#pending = finish;
+            try {
+                this.stream.write(value, (error) => finish(error ? new RemoteDesktopError('DESKTOP_TRANSPORT_ERROR') : undefined));
+            }
+            catch {
+                finish(new RemoteDesktopError('DESKTOP_TRANSPORT_ERROR'));
+            }
+        });
+    }
+    dispose() {
+        if (this.stream.destroyed && !this.stream.closed) {
+            this.stream.once('close', () => this.stream.off('error', this.#failed));
+        }
+        else
+            this.stream.off('error', this.#failed);
+        this.stream.off('close', this.#closed);
+        this.stream.off('end', this.#closed);
+        this.signal.removeEventListener('abort', this.#aborted);
+    }
+    #check() {
+        if (this.#error)
+            throw this.#error;
+        if (this.stream.destroyed || this.stream.readableEnded)
+            throw new RemoteDesktopError('DESKTOP_TRANSPORT_ERROR');
+    }
+    #fail(error) {
+        if (this.#error)
+            return;
+        this.#error = error;
+        this.#pending?.(error);
+    }
+    #failed = () => this.#fail(new RemoteDesktopError('DESKTOP_TRANSPORT_ERROR'));
+    #closed = () => this.#fail(new RemoteDesktopError('DESKTOP_TRANSPORT_ERROR'));
+    #aborted = () => this.#fail(new RemoteDesktopError('DESKTOP_SETUP_CANCELLED'));
+}

package/dist/remote-desktop/rfb-input-release.js

@@ -0,0 +1,77 @@
+import { RemoteDesktopError } from './desktop-error.js';
+/** Sends this attachment's held inputs up before closing an unmodified RFB backend.
+ * A successful write does not confirm that the OS or application processed it.
+ */
+export async function submitRfbInputRelease(gate, target, signal) {
+    const snapshot = await abortable(gate.fence(), signal);
+    const bytes = releaseFrames(snapshot);
+    if (!bytes.length)
+        return;
+    if (signal.aborted || target.destroyed || !target.writable)
+        throw new RemoteDesktopError('DESKTOP_NATIVE_CLEANUP_FAILED');
+    await new Promise((resolve, reject) => {
+        const onError = () => finish(new RemoteDesktopError('DESKTOP_NATIVE_CLEANUP_FAILED'));
+        const onClose = () => finish(new RemoteDesktopError('DESKTOP_NATIVE_CLEANUP_FAILED'));
+        const onAbort = () => finish(new RemoteDesktopError('DESKTOP_NATIVE_CLEANUP_TIMEOUT'));
+        let finished = false;
+        const finish = (error) => {
+            if (finished)
+                return;
+            finished = true;
+            target.off('error', onError);
+            target.off('close', onClose);
+            signal.removeEventListener('abort', onAbort);
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
+        target.once('error', onError);
+        target.once('close', onClose);
+        signal.addEventListener('abort', onAbort, { once: true });
+        try {
+            target.write(bytes, (error) => finish(error ? new RemoteDesktopError('DESKTOP_NATIVE_CLEANUP_FAILED') : undefined));
+        }
+        catch {
+            finish(new RemoteDesktopError('DESKTOP_NATIVE_CLEANUP_FAILED'));
+        }
+    });
+}
+function releaseFrames(snapshot) {
+    // Release ordinary keys before modifiers so the backend interprets their
+    // key-up events under the same modifiers as their key-down events.
+    const modifier = (key) => key === 0xff7e || (key >= 0xffe1 && key <= 0xffee);
+    const keys = [
+        ...snapshot.keys.filter((key) => !modifier(key)),
+        ...snapshot.keys.filter(modifier)
+    ];
+    const frames = keys.map((key) => {
+        const frame = Buffer.alloc(8);
+        frame[0] = 4;
+        frame.writeUInt32BE(key, 4);
+        return frame;
+    });
+    if (snapshot.buttons !== 0) {
+        const frame = Buffer.alloc(6);
+        frame[0] = 5;
+        frame.writeUInt16BE(snapshot.x, 2);
+        frame.writeUInt16BE(snapshot.y, 4);
+        frames.push(frame);
+    }
+    return Buffer.concat(frames);
+}
+async function abortable(operation, signal) {
+    if (signal.aborted) {
+        void operation.catch(() => { });
+        throw new RemoteDesktopError('DESKTOP_NATIVE_CLEANUP_TIMEOUT');
+    }
+    return await new Promise((resolve, reject) => {
+        const abort = () => finish(() => reject(new RemoteDesktopError('DESKTOP_NATIVE_CLEANUP_TIMEOUT')));
+        const finish = (done) => {
+            signal.removeEventListener('abort', abort);
+            done();
+        };
+        signal.addEventListener('abort', abort, { once: true });
+        operation.then((value) => finish(() => resolve(value)), (error) => finish(() => reject(error)));
+    });
+}

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

@@ -0,0 +1,40 @@
+import { submitRfbInputRelease } from './rfb-input-release.js';
+/** Owns a standard RFB connection; submitted releases are not OS execution receipts. */
+export class StandardRfbAttachment {
+    socket;
+    gate;
+    #closing;
+    #closed = false;
+    constructor(socket, gate) {
+        this.socket = socket;
+        this.gate = gate;
+        socket.on('error', this.#ignoreLateError);
+        socket.once('close', () => socket.off('error', this.#ignoreLateError));
+    }
+    #ignoreLateError = () => { };
+    close(signal) {
+        if (this.#closed)
+            return Promise.resolve();
+        if (this.#closing)
+            return this.#closing;
+        this.#closing = this.#close(signal).finally(() => {
+            this.#closing = undefined;
+        });
+        return this.#closing;
+    }
+    async #close(signal) {
+        try {
+            // A lost backend cannot accept releases; still reclaim this attachment.
+            await submitRfbInputRelease(this.gate, this.socket, signal).catch(() => { });
+        }
+        finally {
+            const closed = this.socket.closed
+                ? Promise.resolve()
+                : new Promise((resolve) => this.socket.once('close', resolve));
+            this.socket.destroy();
+            this.gate.dispose();
+            await closed;
+            this.#closed = true;
+        }
+    }
+}

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

@@ -0,0 +1,68 @@
+import { RemoteDesktopError } from './desktop-error.js';
+/** Owns one registered RFB stream and its native cleanup ticket, not the control lease. */
+export class TigerVncAttachment {
+    socket;
+    gate;
+    ticket;
+    #phase = 'active';
+    #closing = false;
+    constructor(socket, gate, ticket) {
+        this.socket = socket;
+        this.gate = gate;
+        this.ticket = ticket;
+        // A pending socket error can arrive after the gate has been disposed.
+        socket.on('error', this.#ignoreLateError);
+        socket.once('close', () => socket.off('error', this.#ignoreLateError));
+    }
+    #ignoreLateError = () => { };
+    async close(signal) {
+        if (this.#phase === 'closed')
+            return;
+        if (this.#closing)
+            throw new RemoteDesktopError('DESKTOP_NATIVE_WAIT_IN_PROGRESS');
+        this.#closing = true;
+        try {
+            if (this.#phase === 'active') {
+                try {
+                    // An already-failed stream is still closed and must receive a native
+                    // cleanup receipt. A write callback alone never proves OS cleanup.
+                    await this.#waitForFence(signal);
+                }
+                finally {
+                    this.socket.destroy();
+                    this.gate.dispose();
+                    this.#phase = 'waiting';
+                }
+            }
+            await this.ticket.wait(signal);
+            this.#phase = 'closed';
+        }
+        finally {
+            this.#closing = false;
+        }
+    }
+    #waitForFence(signal) {
+        const fence = this.gate.fence();
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const finish = (timedOut) => {
+                if (settled)
+                    return;
+                settled = true;
+                signal.removeEventListener('abort', abort);
+                if (timedOut)
+                    reject(new RemoteDesktopError('DESKTOP_NATIVE_CLEANUP_TIMEOUT'));
+                else
+                    resolve();
+            };
+            const abort = () => finish(true);
+            // A failed fence is followed by socket destruction and native cleanup;
+            // the native receipt, not the failed write, decides whether it succeeded.
+            fence.then(() => finish(false), () => finish(false));
+            if (signal.aborted)
+                abort();
+            else
+                signal.addEventListener('abort', abort, { once: true });
+        });
+    }
+}